django框架自动生成api文档（一）

关于swagger

https://www.jianshu.com/p/349e130e40d5
Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：
- Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
- Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
- Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
- Swagger 有一个强大的社区，里面有许多强悍的贡献者。

使用版本

Django==3.1.2

djangorestframework==3.12.2

drf-yasg==1.20.0

此处我的django版本是3.+，而django-swagger不支持3.+版本，所以引用drf-yasg模块，django3.0以下的版本可以直接用django-swagger，这里具体介绍drf-yasg的基本用法

修改settings.py

INSTALLED_APPS = [
 ......
'drf_yasg',  
'rest_framework',
 ......
]

　

添加url.py

项目根目录的url文件最上面，添加文档描述

from drf_yasg.views import get_schema_view
from drf_yasg import openapi

# swager文档
schema_view = get_schema_view(
    openapi.Info(
        title="测试项目API",
        default_version='v1.0',
        description="测试工程接口文档",
        terms_of_service="https://www.baidu.com",
        contact=openapi.Contact(email="baidu@163.com"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
)

添加路由，用于访问swagger

urlpatterns = [
　　...
    # swager
    url(r'^swagger(?P<format>.json|.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
    url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    url(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
]

api文档编写view.py

当然不可能配置了路由以后所有的文档就给你自动生成了，具体的接口配置还需要你自己到实行的view界面进行配置，这里先介绍最简单的配置方法，

from drf_yasg.utils import swagger_auto_schema
from rest_framework.views import APIView

class QueryTesterCases(APIView):

    def post(self, request):
        groupId = request.POST.get('groupId')
        beginTime = request.POST.get('beginTime')
        endTime = request.POST.get('endTime')
        return JsonResponse(TapdCasesManage().queryTesterCases(beginTime=beginTime, endTime=endTime, groupId=groupId))

此时一个最简单的接口文档便写好了，可以先打开swagger地址查看接口文档。

启动服务进入：http://127.0.0.1:8000/swagger/

由于我们没有对接口进行任何描述，所以点开接口以后并没有任何接口信息