Django Swagger接口文檔生成

一、概述

引言

當接口開發完成，緊接着需要編寫接口文檔。傳統的接口文檔使用Word編寫，or一些接口文檔管理平台進行編寫，但此類接口文檔維護更新比較麻煩，每次接口有變更，需要手動修改接口文檔。為了改善這種情況，推薦使用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
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

 

 修改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，完整內容如下：

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/

效果如下：

 

 

Swagger UI

http://127.0.0.1:8000/docs/

效果如下：

 

 

點擊users

 

 

點擊get-->try it out

 

 

點擊執行

 

 

結果如下：

 

 

 

這里是返回了一條用戶表數據，"username": "xiao"，就是我新建的超級用戶。

 

點擊Authorize

 

 

輸入新建的超級用戶和密碼

 

 登錄成功后，效果如下：

 

 

 

本文參考鏈接：

https://www.jianshu.com/p/c53de96f3ff1

https://blog.csdn.net/sinat_41622641/article/details/81636682

https://blog.csdn.net/the_brave/article/details/106138396