12 Django Rest Swagger生成api文檔

 01-簡介

Swagger：是一個規範和完整的框架，用於生成、描述、調用和可視化RESTful風格的Web服務。整體目標是使客戶端和文件系統源代碼做爲服務器以一樣的速度來更新。當接口有變更時，對應的接口文檔也會自動更新。

02-安裝

pip install django-rest-swagger

03-配置

# settings.py

INSTALLED_APPS = [
    ...
    # 生成api文檔
    'rest_framework_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,
}

04-配置路由

# api/urls.py

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=[OpenAPIRenderer, SwaggerUIRenderer])

urlpatterns = [
    # swagger接口文檔路由
    url(r'^docs/', schema_view, name="docs"),
    url(r'^', include(router.urls)),
    url(r'login', obtain_jwt_token),

]

05-在views.py裏面補充註釋

'''
        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.
    '''

View Code

class WaterDeviceViewSet(viewsets.ModelViewSet):
    """
        list:
            返回列出全部 水錶設備信息 數據.

        create:
            建立一條 水錶設備信息 數據.

        retrieve:
            返回一個 水錶設備信息 實例.

        update:
            更新一條 水錶設備信息 數據.

        partial_update:
            更新 水錶設備信息數據 的部分字段.

        delete:
            刪除一條 水錶設備信息 數據.
    """

    queryset = WaterDevice.objects.all().order_by('-devcode')
    pagination_class = StandardResultsSetPagination
    serializer_class = WaterDeviceSerialiser