Django Swagger接口文档生成

Swagger优势

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

Django接入Swagger

大致步骤

1.安装drf_yasg
2.进入到setting.py文件，添加django-rest-swagger应用
3.进入到views.py，将之前定义的UserViewSet和GroupViewset补充注释
4.在urls.py中添加get_schema_view辅助函数
5.启动Django服务，检测Swagger接口文档配置效果
环境

python 3.8

Django 3.0.6

djangorestframework== 3.12.4

drf_yasg==1.1.0

安装

drf_yasg==1.1.0

配置

INSTALLED_APPS = [
	...
    'drf_yasg'
]
末尾处添加swagger 配置项
SWAGGER_SETTINGS = {
    # 基础样式
    'SECURITY_DEFINITIONS': {
        "basic":{
            'type': 'basic'
        }
    },
    # 如果需要登录才能够查看接口文档, 登录的链接使用restframework自带的.
    'LOGIN_URL': 'rest_framework:login',
    'LOGOUT_URL': 'rest_framework:logout',
    # 'DOC_EXPANSION': None,
    # 'SHOW_REQUEST_HEADERS':True,
    # 'USE_SESSION_AUTH': True,
    # 'DOC_EXPANSION': 'list',
    # 接口文档中方法列表以首字母升序排列
    'APIS_SORTER': 'alpha',
    # 如果支持json提交, 则接口文档中包含json输入框
    'JSON_EDITOR': True,
    # 方法列表字母排序
    'OPERATIONS_SORTER': 'alpha',
    'VALIDATOR_URL': None,
}

配置根目录下的URL:

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 +=[
	url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
	url(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
 ]

@swagger_auto_schema(
        operation_summary="知识库详情页",
        responses={
            "200": KnowledgeBaseRetrieveSerializer(many=True),
        },
        operation_description="知识库详情页",
    )
    字段详解
   operation_summary： 操作摘要字符串
   responses： 记录的手动响应的字典
   operation_description： 操作描述覆盖
   method：对于多方法视图，选项应应用于的 http 方法
   methods：对于多方法视图，选项应应用于的 http 方法
   auto_schema：用于生成 Operation 对象的自定义类；这覆盖了类级别的“swagger_schema”属性和“DEFAULT_AUTO_SCHEMA_CLASS”设置，并且可以设置为“无”以防止生成此操作
   request_body：post方法中传的值
   query_serializer：序列化参数
   manual_parameters：要覆盖的参数列表
   operation_id：操作 ID 覆盖；操作 ID 在整个 API 中必须是唯一的
   security： 安全要求覆盖；用于指定哪种身份验证机制
   deprecated：操作的弃用状态
   field_inspectors：额外的序列化器和现场检查器；
   filter_inspectors：额外的过滤器检查器
   paginator_inspectors：额外的分页检查器
   tags：标签覆盖