大家好，我是讯享网，很高兴认识大家。



讯享网

在项目开发中，例如项目的前后端分离开发，需要由前后端相关人员共同定义接口，编写接口文档。之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。一个好的接口文档能够帮助我们快速上手这类项目、便于阅读已有代码、对接接口自动化测试等等

往往一个清晰的API接口文档编写起来比较费时费力，于是有很多接口文档管理工具供我们使用：、、，以及可直接利用接口测试生成接口文档的工具、......

上面列出的工具或多或少都需要花费一定时间去手动维护，在后端项目中可以利用其自带的、第三方库以及更好的自动生成接口文档

参考Core API官网以及drf官网，最终生成的接口文档是以网页的方式呈现的，自动接口文档能生成的是继承自及其子类的视图，具体实现流程如下

讯享网

在配置文件中配置接口文档

讯享网

在总路由中添加接口文档路径

文档路由对应的视图配置为

配置主路由，其中参数为接口文档网站的标题

• 单一方法的视图，可直接使用类视图的文档字符串

讯享网

• 包含多个方法的视图，在类视图的文档字符串中，分开方法定义

• 对于视图集，仍在类视图的文档字符串中分开定义，但是应使用对应的名称进行区分

讯享网

按照上述规范优化好后端接口的视图后，重启项目，访问接口文档

1、上面访问到的接口文档，可以按照右边的指引通过安装，通过命令行操作访问接口文档

2、对于视图集中的名称，在接口文档中叫做

3、接口文档中参数需要在模型类或序列化器类的字段中以选项定义，例如

在模型类中定义

在序列化器中定义

讯享网

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化风格的服务。总体目标是使客户端和文件系统源代码作为服务器以同样的速度来更新。

当接口有变动时，对应的接口文档也会自动更新

优势

• 可生成一个具有互动性的控制台，可快速学习和尝试
• 可生成客户端代码，用于不同平台上、...的实现
• 文件可在许多不同的平台上从代码注释中自动生成
• 有一个强大的社区，里面有许多强悍的贡献者

要提到的是，作为一个工具人，常用的模拟请求工具也是基于的

下面记录在中通过生成接口文档的具体实现流程，参考drf swagger文档

在配置文件中进行配置

配置

讯享网

配置

由于上面开启了访问需要登录，因此需要在路由中开启默认的登录入口，修改主路由

讯享网

完成后重启项目，如果在此之前有进行数据库同步并创建了用户，那么就可以直接访问接口文档的，并跳转到的认证界面进行登录

界面给人以清爽简约的感觉，通过展开接口还可以对接口（传参）进行测试

从年开始就已弃用不再维护了，作者在官方网站上说明了更推荐使用

可以阅读https://github.com/marcgibbons/django-rest-swagger查看更多相关说明

参考drf-yasg官网，是基于和规范的文档自动化生成工具，能够生成比原生更为友好的文档界面

目前的兼容性如下

• 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

在操作下面的步骤前请将第3节相关内容全部注释或还原

讯享网

会暴露种默认路径, 分别为:

• , JSON 格式的 API 定义
• , YAML 格式的 API 定义
• , 基于原生 swagger-ui 样式的前端页面
• , 基于 ReDoc 样式的前端页面

完成后重启项目进行访问

swagger

redoc

4.6.1 get_schema_view的配置

函数 get_schema_view 的作用是返回自动生成 API 文档的视图类, 该函数接受以下参数:

• info: 对象, 具体定义详见 Swagger/OpenAPI 规范, 如果缺省, 默认会用 进行填充
• url: 项目API的基础地址, 如果缺省, 则根据视图所在的位置进行推导
• patterns: 自定义的, 该参数直接透传至
• urlconf: 描述从哪个文件获取路由配置, 缺省值是, 该参数直接透传至
• public: 描述API文档是否公开, 如果未 , 则仅返回当前用户具有权限的接口的文档
• validators: 用于校验自动生成的的校验器, 目前仅支持 和
• generator_class: 自定义生成器类, 该类应该继承自
• authentication_classes: 用于进行登录认证的类
• permission_classes: 用于进行权限校验的类

4.6.2 SchemaView 的配置

通过函数可以获取对应的, 调用该类的或 方法可生成对应的, 将其添加进即可访问到自动生成的 API 文档

• SchemaView.with_ui(renderer, cache_timeout, cache_kwargs): 返回使用指定渲染器的视图函数, 可选的渲染器有: , 。
• SchemaView.without_ui(cache_timeout, cache_kwargs): 返回无的视图函数, 该函数可以返回格式的文档

以上两个函数均支持通过 或 配置缓存参数

4.6.3 缓存的配置

由于通常在服务运行期间不会发生改变, 因此 使用内置的 实现开箱即用的缓存功能, 只需要配置对应的参数即可启用, 对应参数解释如下:

• cache_timeout: 用于指定缓存的生存时间
• cache_kwargs: 用于传递 cache_page 允许接受的非位置参数, 如 (指定 cache backend), (缓存的前缀) 等等, 详见官方文档

需要注意的是, 由于 drf-yasg 支持针对不同用户返回不一样的 API 文档(通过public、authentication_classes、permission_classes等参数配置), 因此对于不同用户(通过HTTP 请求头中的 Cookie 和 Authorization 进行区分), 会在内存中分别进行缓存。

4.6.4 校验文档有效性

为保证自动生成文档的有效性, 可以通过在中设置 参数开启校验自动化生成文档是否符合规范的功能

4.6.5 代码自动生成

使用规范生成文档的好处之一, 就是能通过文档自动生成不同语言的 SDK，该功能由swagger-codegen提供

see you ~

参考：

http://blog.shabbywu.cn/posts/2020/04/15/python-auto-doc-for-drf.html