0013 COREAPI自动生成接口文档
作者：互联网
CoreAPI是基于djangorestframework框架下的自动文档生成器，只要按DRF规则写的路由，CoreAPI就可以自动生成接口文档。
1 编写DRF视图
编写DRF视图有多种方式，
本文本主要展示接口文档的自动生成。故编写一个最简单的视图。
1.1 新增一个视图文件
在Examples/views目录下，创建一个CoreAPI.py文件，其中创建了两个类，代码如下：
from django.shortcuts import render
from rest_framework.views import APIView
from django.http import QueryDict
from rest_framework.response import Response
from rest_framework import status
class CoreAPI(APIView):
@classmethod
def get(cls, request):
"""
【功能描述】主要用于描述模块功能</br>
【模块元素】用于描述模块中存在的相关元素</br>
【返回参数】用于描述模块的返回参数</br>
"""
return render(request, 'exp-home.html')
@classmethod
def post(cls, request):
"""
【功能描述】用于保存表</br>
【返回参数】用于返回模块的返回参数。</br>
"""
username = request.POST.get('user')
data = QueryDict(request.body.decode("utf-8"), encoding="utf-8").dict()
return Response(data, status=status.HTTP_200_OK)
class LoginHome(APIView):
@classmethod
def get(cls, request):
"""
返回登录页面。登录页面主要包括以下功能：</br>
【快捷登录】</br>
包括四个元素手机号输入框，发送验证码按钮，验证码输入框，确定按钮</br>
【密码登录】</br>
包括两个元素：1 用户名或手机号 2 密码</br>
【找回密码】</br>
是一个找回密码的标签，用于跳转到找回密码页面
"""
return render(request, 'exp-home.html')
1.2 修改ExpHome.py视图文件
之前ExpHome.py文件中，主要用于返回一个网页，是Django本身的类方法。继承来自View，只继承APIView改成DRF框架，就可以生成到接口文档中了。
from django.views.generic import View
from django.shortcuts import render
from rest_framework.views import APIView
class ExoHome(APIView):
@classmethod
def get(cls, request):
"""
【功能描述】主要用于示例展示</br>
【返回参数】返回用户请求的网页</br>
"""
return render(request, 'exp-home.html')
2 修改Examples分路由
from django.urls import path
from Applications.Examples.views import ExpHome, CoreAPI
urlpatterns = [
path('ExpHome/', ExpHome.ExoHome.as_view()),
path('CoreAPI/', CoreAPI.CoreAPI.as_view()),
path('LoginHome/', CoreAPI.LoginHome.as_view()),
]
3 修改工程总路由
from django.contrib import admin
from django.urls import path, include
from rest_framework.documentation import include_docs_urls
DESCRIPTION = """
包括仝恒绩效云所有接口文档。包括以下应用：
1 Authentication:认证服务应用
2 Organization: 组织机构应用
"""
urlpatterns = [
path('admin/', admin.site.urls),
path('Examples/', include('Applications.Examples.urls')),
path('docs/', include_docs_urls(title='API接口文档', description=DESCRIPTION)),
]
4 运行工程，就可以看到接口文档的效果了。
5 编写继承类
由于CoreAPI没有对于GET方法请求参数的描述，故需要先编写一个继承类，使得用户可以在序列化器中直接明确相应的备注。
在GeneralTools下创建一个CustomSchema.py文件。内容如下：
from rest_framework.schemas import AutoSchema
class CustomSchema(AutoSchema):
"""
自定义AutoSchema，为view手动添加注释
"""
def get_manual_fields(self, path, method):
"""
location有下列可选选项可以选：
path 包含在模板化URI中。例如，url值/products/{product_code}/可以与"path"字段一起使用。
query 包含在URL查询参数中。例如?search=sale。通常用于GET请求。
form 包含在请求正文中，作为JSON对象或HTML表单的单个项目。例如{"colour": "blue", ...}。通常的POST，PUT和PATCH请求。"form"单个链接上可以包含多个字段。
header 包含在请求头中，可以自定义。
{
'get': [
coreapi.Field(name="mobile", required=True, location="path", schema=coreschema.String(description='手机号')),
coreapi.Field(name="name", required=True, location="query", schema=coreschema.String(description='用户名')),
coreapi.Field(name="password", required=True, location="query", schema=coreschema.String(description='密码')),
],
'post': [
coreapi.Field(name="mobile", required=True, location="path", schema=coreschema.String(description='手机号')),
coreapi.Field(name="subject", required=True, location="query", schema=coreschema.String(description='邮件主题')),
coreapi.Field(name="message", required=True, location="query", schema=coreschema.String(description='邮件正文')),
coreapi.Field(name="to_email", required=True, location="query", schema=coreschema.String(description='收件人')),
],
}
"""
# 可能是list，也可能是dict
manual_fields = super(CustomSchema, self).get_manual_fields(path, method)
if type(manual_fields) == list:
return manual_fields
else:
# dict
for k, v in self._manual_fields.items():
if method.lower() == k.lower():
return v
else:
return []
标签：COREAPI,CoreAPI,0013,name,request,文档,location,import,path 来源： https://www.cnblogs.com/dorian/p/12368614.html