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