本文以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_urlsurlpatterns = [...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 openapischema_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=[请求字段],
还有很多使用参数官网使用即可。
