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

class WaterDeviceViewSet(viewsets.ModelViewSet):
    """
        list:
            返回列出所有 水表設備信息 數據.

        create:
            創建一條 水表設備信息 數據.

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

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

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

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

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