[PPJ_16] Django接入Swagger，生成Swagger接口文档-操作解析

目录结构

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

一、Swagger概述

1.引言

当接口开发完成，紧接着需要编写接口文档。传统的接口文档使用Word编写，or一些接口文档管理平台进行编写，但此类接口文档维护更新比较麻烦，每次接口有变更，需要手动修改接口文档。为了改善这种情况，推荐使用Swagger来管理接口文档，实现接口文档的自动更新。

2.Swagger简介

Swagger：是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统源代码作为服务器以同样的速度来更新。当接口有变动时，对应的接口文档也会自动更新。

如：接口测试站点（http://httpbin.org/#/），也是利用Swagger来生成接口文档

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

二、Django接入Swagger

1.安装django-rest-swagger

pip install django-rest-swagger

本系统同时安装了Python2和Python3，本次采用Python3，对应命令调整为：
pip3 install django-rest-swagger

pip3 list查看已安装的包文件，成功安装后即可查看到django-rest-swagger的安装版本号

2.进入到setting.py文件，添加django-rest-swagger应用

在INSTALLED_APPS = []的中括号中添加'rest_framework_swagger',这一项，如下：

3.进入到views.py，将之前定义的UserViewSet和GroupViewset补充注释

• 在 class UserViewSet 下方添加不同请求方式对应不同响应的多行注释：

    '''
        retrieve:
            Return a user instance.

        list:
            Return all users,ordered by most recent joined.

        create:
            Create a new user.

        delete:
            Remove a existing user.

        partial_update:
            Update one or more fields on a existing user.

        update:
            Update a user.
    '''

注释含义说明：

功能项	功能说明
retrieve	Return a user instance. 返回一个用户实例（查）
list	Return all users,ordered by most recent jonined. 返回列出所有用户（查）
create	Create a new user. 创建一个新用户（增）
delete	Remove a existing user. 移除一个已存在的用户（删）
partial_update	Update one or more fields on a existing user. 更新用户的一个or多个字段（改；部分更新）
update	Update a user. 更新一个用户（改；全部更新）

• 在 class GroupsViewSet 下方添加多行注释：

    '''
        retrieve:
            Return a group instance.

        list:
            Return all groups,ordered by most recent joined.

        create:
            Create a new group.

        delete:
            Remove a existing group.

        partial_update:
            Update one or more fields on a existing group.

        update:
            Update a group.
    '''

以上在UserViewSet和GroupViewset类中添加多行注释完成后，完整的views.py文件代码如下：

from django.shortcuts import render
from django.contrib.auth.models import User,Group
from rest_framework import viewsets
from API.serializers import UserSerializer,GroupSerializer

# Create your views here.

# viewsets通过serializer_class找到对应的serializers
class UserViewSet(viewsets.ModelViewSet):
    '''
        retrieve:
            Return a user instance.

        list:
            Return all users,ordered by most recent joined.

        create:
            Create a new user.

        delete:
            Remove a existing user.

        partial_update:
            Update one or more fields on a existing user.

        update:
            Update a user.
    '''
    queryset = User.objects.all()   # 将User的所有对象赋给queryset，并返回对应值
    serializer_class = UserSerializer   # 指向UserSerializer

class GroupViewSet(viewsets.ModelViewSet):
    '''
        retrieve:
            Return a group instance.

        list:
            Return all groups,ordered by most recent joined.

        create:
            Create a new group.

        delete:
            Remove a existing group.

        partial_update:
            Update one or more fields on a existing group.

        update:
            Update a group.
    '''
    queryset = Group.objects.all()
    serializer_class = GroupSerializer

4.在urls.py中添加get_schema_view辅助函数

将以下三个代码片段添加到urls.py文件代码中的不同位置

• 片段1

# 导入辅助函数get_schema_view
from rest_framework.schemas import get_schema_view
# 导入两个类
from rest_framework_swagger.renderers import SwaggerUIRenderer,OpenAPIRenderer

• 片段2

# 利用辅助函数引入所导入的两个类
schema_view = get_schema_view(title='API',renderer_classes=[SwaggerUIRenderer,OpenAPIRenderer])

• 片段3

path('docs/',schema_view,name='docs')   # 配置docs的url路径

添加完成的效果如下：

urls.py文件的完整代码：

"""Django_Restful URL Configuration

The `urlpatterns` list routes URLs to views. For more information please see:
    https://docs.djangoproject.com/en/2.1/topics/http/urls/
Examples:
Function views
    1. Add an import:  from my_app import views
    2. Add a URL to urlpatterns:  path('', views.home, name='home')
Class-based views
    1. Add an import:  from other_app.views import Home
    2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
Including another URLconf
    1. Import the include() function: from django.urls import include, path
    2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
"""

from django.contrib import admin
from django.urls import path    # 路径模块
from django.conf.urls import include    # 控制添加路径的模块
from rest_framework import routers  # 路由配置模块
from API import views   # 视图模块

# 导入辅助函数get_schema_view
from rest_framework.schemas import get_schema_view
# 导入两个类
from rest_framework_swagger.renderers import SwaggerUIRenderer,OpenAPIRenderer


router = routers.DefaultRouter()    # 创建路由对象
router.register(r'users',views.UserViewSet) # 调用register方法，配置Users的路由
router.register(r'groups',views.GroupViewSet)   # 配置Groups路由

# 利用辅助函数引入所导入的两个类
schema_view = get_schema_view(title='API',renderer_classes=[SwaggerUIRenderer,OpenAPIRenderer])


# 配置url
urlpatterns = [
    path('admin/', admin.site.urls),
    path('',include(router.urls)),  # 代表位于根路径的主域名(http://127.0.0.1:8000)
    path('api-auth/',include('rest_framework.urls',namespace='rest_framework')), # api-auth对应授权登录url
    path('docs/',schema_view,name='docs')   # 配置docs的url路径
]

5.启动Django服务，检测Swagger接口文档配置效果

以上配置完成后，启动Django服务
浏览器访问URL：http://127.0.0.1:8000/docs/
UI界面效果：

展开groups、users，即可查看到其前在views.py文件中添加的关于不同请求对应不同响应的多行注释，已在Swagger UI界面的请求类型区域被有效识别显示，具体如下：

选取users类别下的某个GET请求方式为例，对应URL格式：
http://127.0.0.1:8000/users/{id}/
其中，参数id表示用户的编号

输入id=2，执行Request URL：http://127.0.0.1:8000/users/2/
Response数据（Response Body、Response Headers、Status Code）如下：

以上，Swagger接口文档已可正常生成，本次配置完成