swagger在线接口文档

目前为止，接口开发到了一定的阶段，已经初具规模，在和前端对接之前，需要规范化接口文档。如果纯手写的话工作量大且重复枯燥，因此，可以用工具帮助我们实现接口文档的自动生成。

Django REST Swagger 项目已经不维护了，并且不支持最新的Django，所以可以选择 drf-yasg 项目作为接口文档生成器。yasg 的功能非常强大，可以同时支持多种文档格式。

drf-yasg安装与配置

安装drf-yasg

pip install -U drf-yasg 	# 安装最新版 drf-yasg

配置drf-yasg

drf-yasg 也属于django的插件，因此需要注册到 settings.py 配置文件中

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'sqtp',
    'rest_framework', # 配置djangorestframework
    'drf_yasg', # 配置drf-yasg (API文档生成器)
]

drf_yasg需要与django.contrib.staticfiles配套使用，一般情况下，项目创建都会在INSTALLED_APPS列表中注册这个工具，如果没有，需要手动添加

修改sqtp应用app目录下的urls.py文件

from django.urls import path,include
from sqtp import views as sqtp_view

# 使用rest框架自带的路由器生成路由列表
from rest_framework.routers import DefaultRouter

# 使用 drf_yasg API文档生成器 视图和openapi
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

# 导入权限控制模块
from rest_framework import permissions

# 文档视图
schema_view = get_schema_view(
    # API 信息
    openapi.Info(
        title='SQTP API',   # API文档标题
        default_version='V1',   # 版本信息
        description='SQTP 接口文档',    # 描述内容
        terms_of_service='https://test.com',    # 开发团队地址
        contact=openapi.Contact(email='https://test.@163com',url='https://test.com'),   # 联系人信息：邮件、网址
        license=openapi.License(name='Test License'),    # 证书
    ),
    public=True,    # 是否公开
    permission_classes=(permissions.AllowAny,)   # 设置用户权限

)

router = DefaultRouter()
router.register(r'requests',sqtp_view.RequestViewSet)

urlpatterns = [
    path('',include(router.urls)),
    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'),   #文档模式
]

首先通过 get_schema_view函数去配置文档视图的信息，除了权限控制，其余信息只是作为展示用。

drf_yasg API文档生成器支持两种模式，互动模式和文档模式，分别配置其对应的路由swagger/和redoc/，并通过with_ui方法去配置这两种模式。

互动模式

启动项目，在浏览器中输入http://127.0.0.1:8888/swagger/，进入互动模式，顶部展示的是文档信息，也就是schema_view里配置的内容

列表中展示的是接口信息

点击后可通过swagger进行接口测试，页面展示接口的传参内容，点击右上角Try it out

对接口信息进行修改后，点击Execute按钮，发送请求，页面会返回响应结果

文档模式

在浏览器中输入http://127.0.0.1:8888/redoc/，进入文档模式

该种模式下不能进行接口测试，但接口参数内容、参数信息和响应内容，都很详细

定制化用法（viewset模式）

当前的接口文档是没有定制化注释的，比如某个接口的功能是什么，从名称根据Rest风格就能猜测出来，但如果是些定制化的接口就需要加些注释了。

修饰视图装饰器api_view

修改sqtp应用app目录下的views.py文件，添加以下代码。比如这个接口，单纯就是返回一些信息，不想让用户访问，但是又不想让用户知道他没权限访问。这个接口并没有与数据库有数据交互，只是用了视图装饰器 api_view 处理请求和响应

@api_view('GET')
def testing_api(request):
    return Response(data={"retcode":status.HTTP_200_OK,'msg':'loading...'})

这里可以采用swagger_auto_schema装饰器修饰视图函数，operation_summary参数指 接口摘要信息、operation_description指 接口描述信息

# 导入swagger_auto_schema装饰器
from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(method='GET',operation_summary='定制化API', operation_description='loading...')
@api_view('GET')
def testing_api(request):
    return Response(data={"retcode":status.HTTP_200_OK,'msg':'loading...'})

修改sqtp应用app目录下的urls.py文件，添加路由

urlpatterns = [
    path('',include(router.urls)),
    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'),   #文档模式
    path('testing/',sqtp_view.testing_api),
]

启动项目，在浏览器中输入http://127.0.0.1:8888/swagger/，进入互动模式，可以发现文档中新增了一个接口信息，展示swagger_auto_schema装饰器中的描述信息

修饰视图集

如果视图采用类或者视图集，视图函数本身是继承父类，没有出现在编写的代码中该如何自定义接口描述呢？

修改sqtp应用app目录下的views.py文件，添加以下代码

class RequestViewSet(viewsets.ModelViewSet):
    queryset = Request.objects.all()  # 数据的查询集
    serializer_class = RequestSerializer

这时，可以采用django装饰器配合swagger的装饰器来实现

# 导入django装饰器
from django.utils.decorators import method_decorator

@method_decorator(name='list',decorator=swagger_auto_schema(operation_summary='查询数据', operation_description='查询所有教师数据'))
@method_decorator(name='create',decorator=swagger_auto_schema(operation_summary='新增数据', operation_description='新增教师信息数据'))
@method_decorator(name='destroy',decorator=swagger_auto_schema(operation_summary='删除数据', operation_description='删除指定教师信息数据'))
class RequestViewSet(viewsets.ModelViewSet):
    queryset = Request.objects.all()  # 数据的查询集
    serializer_class = RequestSerializer

相当于是在django装饰器中再使用swagger的装饰器

这里参数 name，list指查询所有数据；create指新增数据；update指修改数据；destroy指删除数据；retrieve指查询单条数据；