Django Swagger接口文档生成

谁践踏了优雅 2023-02-23 09:30 16阅读 0赞

# 一、概述 #

## 引言 ##

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

## 简介 ##

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

![format_png][]

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

## Swagger优势 ##

1）Swagger可生成一个具有互动性的API控制台，开发者可快速学习和尝试API  
2）Swagger可生成客户端SDK代码，用于不同平台上（Java、Python...）的实现  
3）Swagger文件可在许多不同的平台上从代码注释中自动生成  
4）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接口文档配置效果

## 环境说明 ##

python 3.7.3
    
    Django 2.2.4
    
    djangorestframework==3.9.2
    
    django-rest-swagger 2.2.0

## 安装模块 ##

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新建一个项目：t\_swagger，app名为api

![format_png 1][]

修改t\_swagger/settings.py，增加2行

INSTALLED_APPS = [
        'django.contrib.admin',
        'django.contrib.auth',
        'django.contrib.contenttypes',
        'django.contrib.sessions',
        'django.contrib.messages',
        'django.contrib.staticfiles',
        'api.apps.ApiConfig',
        'rest_framework',
        'rest_framework_swagger'
    ]

在swagger/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 ###

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

# 序列化
    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__"

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

## 配置views.py ##

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

![aHR0cHM6Ly9pbWFnZXMuY25ibG9ncy5jb20vT3V0bGluaW5nSW5kaWNhdG9ycy9Db250cmFjdGVkQmxvY2suZ2lm][] ![aHR0cHM6Ly9pbWFnZXMuY25ibG9ncy5jb20vT3V0bGluaW5nSW5kaWNhdG9ycy9FeHBhbmRlZEJsb2NrU3RhcnQuZ2lm][]

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

**注意：这里不需要return，它会返回表数据的。**

## 配置urls.py ##

修改文件t\_swagger/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

**注意：密码必须符合复杂性要求。**

## 启动项目 ##

直接使用Pycharm启动即可。

# 三、访问页面 #

## drf自带的接口UI ##

http://127.0.0.1:8000/

效果如下：

![format_png 2][]

## Swagger UI ##

http://127.0.0.1:8000/docs/

效果如下：

![format_png 3][]

点击users

![format_png 4][]

点击get-->try it out

![format_png 5][]

点击执行

![format_png 6][]

结果如下：

![format_png 7][]

这里是返回了一条用户表数据，"username": "xiao"，就是我新建的超级用户。

点击Authorize

![format_png 8][]

输入新建的超级用户和密码

![format_png 9][]

登录成功后，效果如下：

![format_png 10][]

本文参考链接：

[https://www.jianshu.com/p/c53de96f3ff1][https_www.jianshu.com_p_c53de96f3ff1]

[https://blog.csdn.net/sinat\_41622641/article/details/81636682][https_blog.csdn.net_sinat_41622641_article_details_81636682]

[https://blog.csdn.net/the\_brave/article/details/106138396][https_blog.csdn.net_the_brave_article_details_106138396]

[format_png]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcyMDIwLmNuYmxvZ3MuY29tL2Jsb2cvMTM0MTA5MC8yMDIwMDcvMTM0MTA5MC0yMDIwMDcwNjE1NDUzNjcyNS0yMDE1OTgxNzQ3LnBuZw?x-oss-process=image/format,png
[http_httpbin.org]: http://httpbin.org/#/
[format_png 1]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcyMDIwLmNuYmxvZ3MuY29tL2Jsb2cvMTM0MTA5MC8yMDIwMDcvMTM0MTA5MC0yMDIwMDcwNjE1NTc0NzA4MS0yNTE1NDM4MDgucG5n?x-oss-process=image/format,png
[aHR0cHM6Ly9pbWFnZXMuY25ibG9ncy5jb20vT3V0bGluaW5nSW5kaWNhdG9ycy9Db250cmFjdGVkQmxvY2suZ2lm]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWFnZXMuY25ibG9ncy5jb20vT3V0bGluaW5nSW5kaWNhdG9ycy9Db250cmFjdGVkQmxvY2suZ2lm
[aHR0cHM6Ly9pbWFnZXMuY25ibG9ncy5jb20vT3V0bGluaW5nSW5kaWNhdG9ycy9FeHBhbmRlZEJsb2NrU3RhcnQuZ2lm]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWFnZXMuY25ibG9ncy5jb20vT3V0bGluaW5nSW5kaWNhdG9ycy9FeHBhbmRlZEJsb2NrU3RhcnQuZ2lm
[format_png 2]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcyMDIwLmNuYmxvZ3MuY29tL2Jsb2cvMTM0MTA5MC8yMDIwMDcvMTM0MTA5MC0yMDIwMDcwNjE2MjIxODYyMC0xNDUwMjcwOTEyLnBuZw?x-oss-process=image/format,png
[format_png 3]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcyMDIwLmNuYmxvZ3MuY29tL2Jsb2cvMTM0MTA5MC8yMDIwMDcvMTM0MTA5MC0yMDIwMDcwNjE2MjM0MjI1Ny0xODIyMzkyOTkucG5n?x-oss-process=image/format,png
[format_png 4]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcyMDIwLmNuYmxvZ3MuY29tL2Jsb2cvMTM0MTA5MC8yMDIwMDcvMTM0MTA5MC0yMDIwMDcwNjE2MjQxNTY2MC0xNzYyNzEwNjM2LnBuZw?x-oss-process=image/format,png
[format_png 5]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcyMDIwLmNuYmxvZ3MuY29tL2Jsb2cvMTM0MTA5MC8yMDIwMDcvMTM0MTA5MC0yMDIwMDcwNjE2MjQ1MDAzNS00MDkxOTM0NTkucG5n?x-oss-process=image/format,png
[format_png 6]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcyMDIwLmNuYmxvZ3MuY29tL2Jsb2cvMTM0MTA5MC8yMDIwMDcvMTM0MTA5MC0yMDIwMDcwNjE2MjUyNjcyNi0xOTgzMzA2Njg2LnBuZw?x-oss-process=image/format,png
[format_png 7]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcyMDIwLmNuYmxvZ3MuY29tL2Jsb2cvMTM0MTA5MC8yMDIwMDcvMTM0MTA5MC0yMDIwMDcwNjE2MjU1NDc5NS0xMzE3NDg5NTU0LnBuZw?x-oss-process=image/format,png
[format_png 8]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcyMDIwLmNuYmxvZ3MuY29tL2Jsb2cvMTM0MTA5MC8yMDIwMDcvMTM0MTA5MC0yMDIwMDcwNjE2MjcwOTUxMi0yNDE2MDE3NzIucG5n?x-oss-process=image/format,png
[format_png 9]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcyMDIwLmNuYmxvZ3MuY29tL2Jsb2cvMTM0MTA5MC8yMDIwMDcvMTM0MTA5MC0yMDIwMDcwNjE2Mjc1Nzg2Ni0yMDM0NjIyMDEucG5n?x-oss-process=image/format,png
[format_png 10]: http://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcyMDIwLmNuYmxvZ3MuY29tL2Jsb2cvMTM0MTA5MC8yMDIwMDcvMTM0MTA5MC0yMDIwMDcwNjE2MjgzNjQ4NC0xODM5OTQ4OTg3LnBuZw?x-oss-process=image/format,png
[https_www.jianshu.com_p_c53de96f3ff1]: https://www.jianshu.com/p/c53de96f3ff1
[https_blog.csdn.net_sinat_41622641_article_details_81636682]: https://blog.csdn.net/sinat_41622641/article/details/81636682
[https_blog.csdn.net_the_brave_article_details_106138396]: https://blog.csdn.net/the_brave/article/details/106138396