Django-swagger的配置（百分之90成功）

一、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有一个强大的社区，里面有许多强悍的贡献者

三：配置步骤

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

四：环境说明

注意：版本必须一致，否则会出现其他问题

• python 3.7.xxx
• Django 2.2.4
• djangorestframework==3.9.2
• django-rest-swagger 2.2.0

二、Django接入Swagger
1.安装django-rest-swagger

五：安装

安装模块

pip3 install djangorestframework==3.9.2

注意：djangorestframework版本不能高于3.9.2，否则访问/docs/出现以下错误。

Expected a `coreapi.Document` instance

按照网友的意思，Django Swagger模块已经不维护了，只能支持到3.9.2

另外，django版本不能大于3.x。

六：配置setting.py

使用Pycharm新建一个项目：Marss，app名为Mars

修改Mars/settings.py，增加2行

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'MachineMars.apps.MachinemarsConfig',
    'rest_framework_swagger',	# 新增
    'rest_framework',	# 新增
]

在Marss/settings.py末尾处，增加Swagger配置

# 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,
}

七：配置serializers.py

进入Mars(应用目录)，新建文件serializers.py，内容如下：

这里是将django自带的2个表，进行序列化。

from django.contrib.auth.models import User,Group
from  rest_framework import serializers

class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = "__all__"

class GroupSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Group
        fields = "__all__"

八：配置views.py

进入Mars(应用目录)，修改views.py，完整内容如下：

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


# Create your views here.

class UserViewSet(viewsets.ModelViewSet):
    """
        retrieve:
            返回用户实例
        list:
            返回所有用户，按最近加入的用户排序
        create:
            创建新用户
        delete:
            删除现有用户
        partial_update:
            更新现有用户上的一个或多个字段
        update:
            更新用户
    """
    '''查看，编辑用户的界面'''
    queryset = User.objects.all().order_by('id')
    serializer_class = UserSerializer
    print(serializer_class, type(serializer_class))


class GroupViewSet(viewsets.ModelViewSet):
    '''
        retrieve:
            返回组实例
        list:
            返回按最近加入的组排序的所有组
        create:
            创建新组
        delete:
            删除现有组
        partial_update:
            更新现有组上的一个或多个字段
        update:
            更新一个组
    '''
    '''查看，编辑组的界面'''
    queryset = Group.objects.all()
    serializer_class = GroupSerializer

在 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.更新一个用户（改；全部更新）

八：配置urls.py

修改文件Marss/urls.py，完整内容如下：

from django.contrib import admin
from django.urls import path,include
from rest_framework import routers  # 路由配置模块
from api import views

# 路由
router = routers.DefaultRouter()
router.register(r'users',views.UserViewSet,base_name='user')
router.register(r'groups',views.GroupViewSet)

# 重要的是如下三行
from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPIRenderer
schema_view = get_schema_view(title='Users API', renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer])

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'),
]

九：生成表

python3 manage.py makemigrations
python3 manage.py migrate

十：创建超级用户

python3 manage.py createsuperuser

十一：启动项目

十一.1：访问：drf自带的接口UI：http://127.0.0.1:8000/

十一.2 ：访问：Swagger UI：http://127.0.0.1:8000/docs/