安装
- coreapi (必须)
- Pygments (可选)
- Markdown (可选)
使用coreapi
最新版的DRF(>3.10)中, 需要添加如下配置
REST_FRAMEWORK = {
# 指定用于支持coreapi的Schema
'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}
项目中添加URL
from rest_framework.documentation import include_docs_urls
from django.urls import path, include
urlpatterns = [
path('docs/', include_docs_urls(title='测试平台接口文档')),
]
-
演示：
image.png
image.png
-
添加注释
单一方法的视图
直接给视图类添加注释即可
class ProjectsListView(ListAPIView): """ 返回所有项目信息 """- 多个方法的视图
class ProjectsListCreateView(ListCreateAPIView): """ get: 返回所有项目信息 post: 新建项目 """-
视图集
class ProjectsViewset(viewsets.ModelViewSet): """ create: 创建项目 retrieve: 获取项目详情数据 update: 完整更新项目 partial_update: 部分更新项目 destroy: 删除项目 list: 获取项目列表数据 names: 获取所有项目名称 interfaces: 获取指定项目的所有接口数据 """
添加注释后报告中就会显示描述
image.png
但是drf3.12之后就不会支持，推荐使用另一种
使用drf-yasg
- 安装
pip install drf-yasg
- 添加到INSTALLED_APPS中
INSTALLED_APPS = [
...
'drf_yasg',
...
]
- 在全局路由文件urls.py文件中添加配置
# from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
schema_view = get_schema_view(
openapi.Info(
title="Lemon API接口文档平台", # 必传
default_version='v1', # 必传
description="这是一个美轮美奂的接口文档",
terms_of_service="http://api.keyou.site",
contact=openapi.Contact(email="keyou100@qq.com"),
license=openapi.License(name="BSD License"),
),
public=True,
# permission_classes=(permissions.AllowAny,), # 权限类
)
urlpatterns = [
#三种不同风格的接口文档，自选其一
re_path(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
]
验证一
http://127.0.0.1:8000/swagger/
image.png
image.png
演示二
http://127.0.0.1:8000/swagger/
image.png
演示三
image.png
以上三种第一种适合平台集成，第二种存在交互可以操作验证，第三种更加详细
