drf的接口文档生成与管理
共 11091字,需浏览 23分钟
·
2021-04-12 06:38
目录
1、接口文档简述
2、Core API 生成接口文档
2.1 安装 Core API 库
2.2 设置接口文档访问路径
2.3 文档描述说明的定义位置
2.4 访问查看
2.5 补充说明
3、Swagger 生成接口文档
3.1 Swagger 介绍
3.2 安装 django-rest-swagger 库
3.3 配置 app 及 swagger
3.4 配置相关路由
3.5 访问查看
3.6 说明
4、drf-yasg(Swagger 升级版)
4.1 drf-yasg 介绍
4.2 安装 drf-yasg 库
4.3 配置 app
4.4 配置路由 url
4.5 访问查看
4.6 更多配置及说明
1、接口文档简述
在项目开发中,例如web
项目的前后端分离开发,需要由前后端相关人员共同定义接口,编写接口文档。之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护。一个好的接口文档能够帮助我们快速上手这类项目、便于阅读已有代码、对接接口自动化测试等等
往往一个清晰的 API 接口文档编写起来比较费时费力,于是有很多接口文档管理工具供我们使用:YApi
、ShowDoc
、DocWay
,以及可直接利用接口测试生成接口文档的工具Postman
、Apipost
......
上面列出的工具或多或少都需要花费一定时间去手动维护,在drf
后端项目中可以利用其自带的Core API
、第三方库Swagger
以及更好的drf-yasg
自动生成接口文档
2、Core API 生成接口文档
参考Core API 官网[1]以及drf 官网[2],最终生成的接口文档是以网页的方式呈现的,自动接口文档能生成的是继承自APIView
及其子类的视图,具体实现流程如下
2.1 安装 Core API 库
pip3 install coreapi
pip3 freeze > requirements.txt
2.2 设置接口文档访问路径
在配置文件settings.py
中配置接口文档
REST_FRAMEWORK = {
...
# core api接口文档
'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema',
}
在总路由中添加接口文档路径
文档路由对应的视图配置为rest_framework.documentation.include_docs_urls
配置url
主路由,其中参数title
为接口文档网站的标题
from rest_framework.documentation import include_docs_urls
urlpatterns = [
...
path('docs/', include_docs_urls(title='API document')),
]
2.3 文档描述说明的定义位置
单一方法的视图,可直接使用类视图的文档字符串
class HostListView(generics.ListAPIView):
"""
返回所有主机信息.
"""
包含多个方法的视图,在类视图的文档字符串中,分开方法定义
class HostListCreateView(generics.ListCreateAPIView):
"""
get:
返回所有主机信息.
post:
新建主机.
"""
对于视图集 ViewSet
,仍在类视图的文档字符串中分开定义,但是应使用action
对应的名称进行区分
class HostInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
"""
list:
返回主机列表数据
retrieve:
返回主机详情数据
latest:
返回最新的主机数据
read:
修改主机的访问记录
"""
2.4 访问查看
按照上述规范优化好后端接口的视图后,重启项目,访问接口文档
2.5 补充说明
1、上面访问到的接口文档,可以按照右边的指引通过安装coreapi-cli
,通过命令行操作访问接口文档
2、对于视图集ViewSet
中的retrieve
名称,在接口文档中叫做read
3、接口文档中参数Description
需要在模型类或序列化器类的字段中以help_text
选项定义,例如
在模型类中定义
class EnvironmentView(models.Model):
...
name = models.CharField(max_length=32, verbose_name='环境名称', help_text='环境名称')
...
在序列化器中定义
class EnvironmentModelSerializer(serializers.ModelSerializer):
class Meta:
model = Environment
fields = "__all__"
extra_kwargs = {
'name': {
'required': True,
'help_text': '环境名称'
}
...
}
3、Swagger 生成接口文档
3.1 Swagger 介绍
Swagger[3]是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful
风格的Web
服务。总体目标是使客户端和文件系统源代码作为服务器以同样的速度来更新。
当接口有变动时,对应的接口文档也会自动更新
Swagger
优势
Swagger
可生成一个具有互动性的API
控制台,可快速学习和尝试API
Swagger
可生成客户端SDK
代码,用于不同平台上Java
、Python
...的实现Swagger
文件可在许多不同的平台上从代码注释中自动生成Swagger
有一个强大的社区,里面有许多强悍的贡献者
要提到的是,作为一个工具人,常用的httpbin
模拟请求工具也是基于swagger
的
下面记录在drf
中通过swagger
生成接口文档的具体实现流程,参考drf swagger 文档[4]
3.2 安装 django-rest-swagger 库
pip3 install django-rest-swagger
pip3 freeze > requirements.txt
3.3 配置 app 及 swagger
在配置文件settings.py
中进行配置
配置app
INSTALLED_APPS = [
...
'rest_framework',
'rest_framework_swagger'
]
配置swagger
# swagger 配置项
SWAGGER_SETTINGS = {
# 基础样式
'SECURITY_DEFINITIONS': {
"basic": {
'type': 'basic'
}
},
# 如果需要登录才能够查看接口文档, 登录的链接使用 restframework 自带的.
'LOGIN_URL': 'rest_framework:login',
'LOGOUT_URL': 'rest_framework:logout',
# 控制API列表的显示方式 None 所有操作均已折叠 list 列出所有操作 full 扩展所有操作
'DOC_EXPANSION': None,
# 是否显示请求标头
'SHOW_REQUEST_HEADERS': True,
# 切换使用Django Auth作为身份验证机制 将其设置为True将会在Swagger UI上显示一个登录/注销按钮,并将csrf_tokens发布到API
'USE_SESSION_AUTH': True,
# 接口文档中方法列表以首字母升序排列
'APIS_SORTER': 'alpha',
# 如果支持json提交, 则接口文档中包含json输入框
'JSON_EDITOR': True,
# 方法列表字母排序
'OPERATIONS_SORTER': 'alpha',
# 在线模式验证器的URL 修改为指向本地安装,或设置None为禁用
'VALIDATOR_URL': None,
}
3.4 配置相关路由
由于上面开启了访问swagger
需要登录,因此需要在路由中开启drf
默认的登录入口,修改主路由
from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPIRenderer
schema_view = get_schema_view(title='Users API', renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer])
urlpatterns = [
# drf认证
path(r'api-auth/', include('rest_framework.urls', namespace='rest_framework')),
# swagger接口文档
path('docs/', schema_view, name='docs'),
...
]
3.5 访问查看
完成后重启项目,如果在此之前有进行数据库同步并创建了用户,那么就可以直接访问接口文档的url
,并跳转到drf
的认证界面进行登录
swagger
界面给人以清爽简约的感觉,通过展开接口还可以对接口(传参)进行测试
3.6 说明
Django REST Swagger
从19
年开始就已弃用不再维护了,作者在官方网站上说明了更推荐使用drf-yasg
可以阅读https://github.com/marcgibbons/django-rest-swagger查看更多相关说明
4、drf-yasg(Swagger 升级版)
4.1 drf-yasg 介绍
参考drf-yasg 官网[5],drf-yasg
是基于Swagger
和OpenAPI 2.0
规范的API
文档自动化生成工具,能够生成比原生swagger
更为友好的API
文档界面
目前的兼容性如下
Django Rest Framework: 3.10, 3.11, 3.12 Django: 2.2, 3.0, 3.1 Python: 3.6, 3.7, 3.8, 3.9
4.2 安装 drf-yasg 库
在操作下面的步骤前请将第 3 节swagger
相关内容全部注释或还原
pip3 install drf-yasg
pip3 freeze > requirements.txt
4.3 配置 app
INSTALLED_APPS = [
...
'rest_framework',
'drf_yasg'
]
4.4 配置路由 url
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
...
schema_view = get_schema_view(
# 具体定义详见 [Swagger/OpenAPI 规范](https://swagger.io/specification/#infoObject "Swagger/OpenAPI 规范")
openapi.Info(
title="Snippets API",
default_version='v1',
description="Test description",
terms_of_service="https://www.google.com/policies/terms/",
contact=openapi.Contact(email="contact@snippets.local"),
license=openapi.License(name="BSD License"),
),
# public 表示文档完全公开, 无需针对用户鉴权
public=True,
# 可以传递 drf 的 BasePermission
permission_classes=(permissions.AllowAny,),
)
urlpatterns = [
# drf_yasg
re_path(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-spec'),
re_path(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
re_path(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
...
]
drf-yasg
会暴露4
种默认路径endpoint
, 分别为:
/swagger.json
, JSON 格式的 API 定义/swagger.yaml
, YAML 格式的 API 定义/swagger/
, 基于原生 swagger-ui 样式的前端页面/redoc/
, 基于 ReDoc 样式的前端页面
4.5 访问查看
完成后重启项目进行访问
swagger
redoc
4.6 更多配置及说明
4.6.1 get_schema_view 的配置
函数 get_schema_view 的作用是返回自动生成 API 文档的视图类, 该函数接受以下参数:
info: Swagger API Info
对象, 具体定义详见 Swagger/OpenAPI 规范[6], 如果缺省,drf-yasg
默认会用DEFAULT_INFO
进行填充url: 项目 API 的基础地址, 如果缺省, 则根据视图所在的位置进行推导 patterns: 自定义的 urlpatterns
, 该参数直接透传至SchemaGenerator
urlconf: 描述从哪个文件获取路由配置, 缺省值是 urls
, 该参数直接透传至SchemaGenerator
public: 描述 API 文档是否公开, 如果未 False
, 则仅返回当前用户具有权限的接口endpoints
的API
文档validators: 用于校验自动生成的 Schema
的校验器, 目前仅支持ssv
和flex
generator_class: 自定义 OpenAPI schema
生成器类, 该类应该继承自OpenAPISchemaGenerator
authentication_classes: 用于 schema view
进行登录认证的类permission_classes: 用于 schema view
进行权限校验的类
4.6.2 SchemaView 的配置
通过函数get_schema_view
可以获取对应的SchemaView
, 调用该类的with_ui
或 without_ui
方法可生成对应的视图函数
, 将其添加进urlpatterns
即可访问到自动生成的 API 文档
SchemaView.with_ui(renderer, cache_timeout, cache_kwargs): 返回使用指定 UI
渲染器的视图函数, 可选的UI
渲染器有:swagger
,redoc
。SchemaView.without_ui(cache_timeout, cache_kwargs): 返回无 UI
的视图函数, 该函数可以返回json/yaml
格式的swagger
文档
以上两个函数均支持通过 cache_timeout
或 cache_kwargs
配置缓存参数
4.6.3 缓存的配置
由于schema
通常在服务运行期间不会发生改变, 因此 drf-yasg
使用django
内置的 cache_page
实现开箱即用的缓存功能, 只需要配置对应的参数即可启用, 对应参数解释如下:
cache_timeout: 用于指定缓存的生存时间 cache_kwargs: 用于传递 cache_page 允许接受的非位置参数, 如 cache
(指定 cache backend),key_prefix
(缓存key
的前缀) 等等, 详见django
官方文档
需要注意的是, 由于 drf-yasg 支持针对不同用户返回不一样的 API 文档(通过public、authentication_classes、permission_classes等参数配置), 因此对于不同用户(通过 HTTP 请求头中的 Cookie 和 Authorization 进行区分), 会在内存中分别进行缓存。
4.6.4 校验文档有效性
为保证自动生成文档的有效性, 可以通过在get_schema_view
中设置 validators
参数开启校验自动化生成文档是否符合OpenAPI2.0
规范的功能
4.6.5 代码自动生成
使用Swagger/OpenAPI
规范生成文档的好处之一, 就是能通过API
文档自动生成不同语言的 SDK,该功能由swagger-codegen[7]提供
see you ~
参考资料
Core API官网: http://core-api.github.io/python-client/
[2]drf官网: https://www.django-rest-framework.org/coreapi/from-documenting-your-api/
[3]Swagger: https://swagger.io/
[4]drf swagger文档: https://django-rest-swagger.readthedocs.io/
[5]drf-yasg官网: https://drf-yasg.readthedocs.io/
[6]Swagger/OpenAPI 规范: https://swagger.io/specification/#infoObject
[7]swagger-codegen: https://github.com/swagger-api/swagger-codegen
http://blog.shabbywu.cn/posts/2020/04/15/python-auto-doc-for-drf.html