Django-接入Swagger接口文档

Django-接入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接口文档配置效果

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

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


3、Django接入Swagger：
(1)安装django-rest-swagger:
pip install django-rest-swagger
pip list查看已安装的包文件，成功安装后即可查看到django-rest-swagger的安装版本号
(2)进入到setting.py文件，添加django-rest-swagger应用:
在INSTALLED_APPS = []的中括号中添加'rest_framework_swagger',这一项，如下：
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'api',
    'rest_framework_swagger',
]
(3)进入到views.py，将之前定义的UserViewSet和GroupViewset补充注释:
在 class UserViewSet 下方添加不同请求方式对应不同响应的多行注释：
    """
    retrieve:
        Return a user instance.
    list:
        Return all users, ordered by most recently joined.
    create:
        Create a new user.
    delete:
        Remove an existing user.
    partial update:
        Update one or more fields on an existing user.
    update:
        Update a user.
    """
在 class GroupsViewSet 下方添加多行注释：
    """
    retrieve:
        Return a group instance.
    list:
        Return all groups, ordered by most recently joined.
    create:
        Create a new group.
    delete:
        Remove an existing group.
    partial update:
        Update one or more fields on an existing group.
    update:
        Update a group.
    """

(4)在urls.py中添加get_schema_view辅助函数:
# 导入辅助函数get_schema_view
from rest_framework.schemas import get_schema_view
# 导入两个类
from rest_framework_swagger.renderers import SwaggerUIRenderer,OpenAPIRenderer

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

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework')),
    path('docs/',schema_view,name='docs'),  #配置docs的url路径
]

(5)启动Django服务，检测Swagger接口文档配置效果:
启动Django服务:cmd打开django安装目录：python manager.py runserver
浏览器访问URL：http://127.0.0.1:8000/docs/