Swagger文档注释

本文以DRF框架为例使用

为什么要接口文档注释

    一. 方便后端调试与后续接口更新；

    二. 对于大型前后端分离项目，前后端人员是分开开发的，甚至前端的人你都不知道远在何处，这时候接口文档的重要性就太重要了。

    三. 接口注释文档常用apidoc和swagger，目前而已swagger较为流行。

本文带你从零到一将swagger用入实际开发

官网URL：https://pypi.org/project/drf-yasg/#quickstart

（本文会把必要操作都实现，不点也可以，毕竟文档全英）

安装：

pip install -U drf-yasg

在外层目录创建目录（命名swagger即可），先创建一个urls.py文件。

全文搜索看你项目的INSTALLED_APPS在哪里，然后在配置文件内加入：

INSTALLED_APPS = [
   ...
   'django.contrib.staticfiles',  # 为swagger的ui css/js文件提供服务时需要
   'drf_yasg',
   ...
]

然后写urls，先在外层的urls写入路由：

from swagger import urls as swagger_urls​urlpatterns = [    ...    url(r'^', include(swagger_urls)),     ...]

swagger/urls.py

下列的swagger和redoc其实就是不同模板的视图展示，甚至还有swagger.json和swagger.yaml的API规范的JSON视图与yaml视图

from django.urls import re_pathfrom rest_framework import permissionsfrom drf_yasg.views import get_schema_viewfrom drf_yasg import openapi​schema_view = get_schema_view(   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=True,   permission_classes=(permissions.AllowAny,),)​urlpatterns = [   path('swagger<format>/', 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')]

可以通过手写路由，完成模糊化配置：

re_path(r"^swagger(?P<format>\.json|\.yaml)$", schema_view.without_ui(cache_timeout=0), name="schema-json"),

此时运行项目，在路径后加/swagger：

可以看到类似这种界面↓：

加/redoc可以看到类似这种界面（Download可导出json或yaml文件）：

到这里swagger集成的初步工作就完成了。

接下来就是去方法中加注解

@swagger_auto_schema

去标记

例如

1、Get方法获取电话号（method为方法，operation_summary为外注解，operation_description用来表示方法+请求路径，manual_parameters用于声明请求参数，responses展示返回信息，默认会使用当前class指定的serializer）：

    @swagger_auto_schema(        method='get',        operation_summary='获取电话',        operation_description="GET /phone/",        manual_parameters=[            openapi.Parameter("id", in_=openapi.TYPE_NUMBER, description="ID", type=openapi.TYPE_NUMBER)        ],        responses={status.HTTP_200_OK:PhoneNumSerializer()})

（manual_parameters中的in_和type需都存在

还有参数depracated=True 表示API已经 被弃用）

2、最简单的使用就↓

    @swagger_auto_schema(        operation_summary='POST摘要',        operation_description='POST的說明：一般用方法+请求路径',    )

还有post添加参数的方式，如：

使用request_body=openapi.Schema(....)，required=[请求字段],

还有很多使用参数官网使用即可。