【DRF配置管理】如何建立swagger风格api接口文档

原文作者：我辈李想
版权声明：文章原创，转载时请务必加上原文超链接、作者信息和本声明。

DRF应用和管理

【DRF配置管理】Django安装DRF框架并生成openapi风格文档
【DRF配置管理】如何实现JWT身份验证
【DRF配置管理】如何使用序列化:验证码、注册和登录
【DRF配置管理】如何结合ORM实现排序、模糊搜索、范围查询
【DRF配置管理】如何在视图类使用get_objects()
【DRF配置管理】如何实现RBAC页面菜单和按钮权限
【DRF配置管理】如何建立coreapi风格api接口文档
【DRF配置管理】如何建立swagger风格api接口文档

---

---

前言

swagger风格的文档在很多语言中都存在，比如jave项目。DRF本身虽然可以实现swagger-ui展示，但是功能不完善，官方推荐的第三方库有drf-yasg 和drf-spectacular 。因为采用的身份验证方式不同，接口文档的设置会存在差异。如果使用的是jwt身份验证，我们需要专门设置对应的headers参数。

---

一、drf-yasg 的使用

1.安装drf-yasg

pip install drf-yasg

2.INSTALLED_APPS 参数

INSTALLED_APPS = [
     ....
    'drf_yasg',
     ...
]

3.REST_FRAMEWORK 参数

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
	    # 自己写的认证类
	    'studentSystemt.apps.user.authen.MyJWTAuthentication'

    ],
}

4.SWAGGER参数

这里针对的是jwt身份验证，实现jwt认证的相关文档生成。

SWAGGER_SETTINGS = {
    'USE_SESSION_AUTH': True,
    'SECURITY_DEFINITIONS': {
        'Token': {
            'type': 'apiKey',  #
            'name': 'Authorization',
            'in': 'header'
        },
    },
}

5.urls路由配置

from django.urls import path, include
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

urlpatterns = [
	...
]

schema_view = get_schema_view(
    openapi.Info(
        title="API接口文档平台",  # 必传
        default_version='v1',  # 必传
        description="这是一个接口文档",
        terms_of_service="http://api.ty.site",
        contact=openapi.Contact(email="ty@qq.com"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),  # 权限类
)
urlpatterns += [
    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'),
]

注释信息参考【DRF配置管理】如何建立coreapi风格接口文档