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 []