1、接口文档简述

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

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

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

2、Core API生成接口文档

参考Core API官网以及drf官网，最终生成的接口文档是以网页的方式呈现的，自动接口文档能生成的是继承自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是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统源代码作为服务器以同样的速度来更新。

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

Swagger优势

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

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

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

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官网，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)
    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 规范, 如果缺省, 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提供

see you ~

参考：

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