012 测试接口编写

1 APIDOC模板

　　在docs下找到edit.py文件，增加如下内容：

#!/usr/bin/env python
# -*- coding: UTF-8 -*-
"""
路径    : edit.py
标题    : APIDOC模板
创建    : 2022-03-29 20:00
更新    : 2022-03-29 20:00
编写    : 陈倚云
"""
"""
@api {GET} /nucleus/DemoView/ 10-081 月度自评 ● 首页查询
@apiVersion 2.0.2
@apiName get_eval_month_evaluate1
@apiGroup 10 评估分析API
@apiDescription <span style="color:#E62F28;font-size:18px;font-weight:bold">使用说明</span></br>
<div style="color:#EB9732;padding:10px;border-radius:8px;font-family:Consolas;font-size:14px;padding:15px">
备注：
<div style="height:10px"></div> //换行
    <span style="color:#C91425">■ </span>
</div>
@apiParam {Integer} user_id 用户id
@apiParam {Integer} dep_id 部门id,为空时为默认部门
@apiParam {Integer} plan_month_id 计划月度id,为空时为默认月度
@apiParam {Integer} role_id 角色id,1-部门月度自评 2-岗位月度自评
@apiParamExample {json} json参数样例
/*
    当前岗位-销售中心员工
    说明：销售中心员工拥有部门月进度填报和岗位月进度填报权限
*/
//1 样例1 销售中心-月进度填报[部门月进度填报]
{
    "user_id": "1",
    "dep_id": "",
    "plan_month_id": "",
    "role_id": "1"
}

//2 样例2：销售中心员工-月进度填报[岗位月进度填报]
{
    "user_id": "1",
    "dep_id": "",
    "plan_month_id": "",
    "role_id": "2"
}
@apiSuccessExample 执行成功:
HTTP 1.1/ 200K
{}
@apiErrorExample 执行失败:
HTTP 1.1/ 404K
{
    "status": 0,
    "msg": "查询失败"
}
"""

 

2 在nucleus APP下，找到view.py，按APIDOC模板编写测试接口：

#!/usr/bin/env python
# -*- coding: UTF-8 -*-
"""
路径    : views.py
标题    : 测试接口
创建    : 2022-04-08 5:50
更新    : 2022-04-08 5:50
编写    : 陈倚云
"""
from django.shortcuts import render

# Create your views here.
import json
from django.shortcuts import HttpResponse
from django.views.generic import View


# Create your views here.
class ApidocTest(View):
    """
    API接口文档测试
    """

    @classmethod
    def get(cls, request):
        """
        @api {GET} /ApidocTest/ APIDOC接口文档测试
        @apiVersion 0.0.1
        @apiName apidoc_test
        @apiGroup 01 测试分组
        @apiDescription <span style="color:#E62F28;font-size:18px;font-weight:bold">使用说明</span></br>
        <div style="color:#EB9732;padding:10px;border-radius:8px;font-family:Consolas;font-size:14px;padding:15px">
        本接口用于测试APIDOC样式文档
        <div style="height:10px"></div>
            <span>■ 1 第一条</span></br>
            <span>■ 2 第二条</span>
        </div>
        @apiParam {String} test_param 上传测试参数
        @apiParamExample {json} ajax 提交参数样例
        /**
            本接口测试参数示例
        */
        {
            "test_param":"录入测试参数"
        }
        @apiSuccessExample 执行成功
        /**
            测试成功后接口返回数据
        */
        {
            'status': 0,
            'return_param': '返回参数' //返回测试参数
        }
        @apiErrorExample 执行失败
        {
            "status": 0,
            "msg": "请求失败!",
            "error_info": { //错误信息
                "errcode": "", //错误代码
                "errdir": "", //错误路径
                "errmsg": "", //错误信息
                "errurl": "" //错误详情跳转
            }
        }
        """
        test_param = {}
        for key in request.GET:
            test_param = json.loads(key)
        test_param = test_param['test_param']
        return HttpResponse(json.dumps({
            'return_param': '测试参数为：' + test_param
        }))

 

3 配置url

　　找到工程配置目录下的urls.py文件，增加测试接口url

from django.contrib import admin
from django.urls import path, include
from django.conf import settings
from django.conf.urls.static import static

import nucleus.views

urlpatterns = [
    path('admin/', admin.site.urls),
    path('ApidocTest/', nucleus.views.ApidocTest.as_view()),
    path('bases/', include('api.bases.urls')),
    path('clients/', include('api.clients.urls')),
    path('managers/', include('api.managers.urls')),
]
urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

 

4 增加publish.py文件

　　在docs目录下，增加publish.py文件，内容如下：

#!/usr/bin/env python
# -*- coding: UTF-8 -*-
"""
路径    : publish.py
标题    : 发布命令
创建    : 2022-03-29 21:56
更新    : 2022-03-29 21:56
编写    : 陈倚云
"""

"""
01 生成接口文档
    apidoc -i api/ -o apidoc
"""

"""
02 字典格式化
    https://tool.oschina.net/codeformat/json/
"""

 

5 编译APIDOC接口文档

　　在Terminal下，执行命令：

　　(csoft_env) D:\DjangoProjects\Projects\CloudSoft\cloud_soft>apidoc -i nucleus/ -o apidoc

　　注意，该命令必须在有manage.py目录下执行，即工程根目录下执行。编译完成后，就可以看到apidoc目录下已经存在接口文档了。

 

6 把style.css样式文件内容拷贝覆盖apidoc/css下的style.css

 

7 启动接口文档

　　windows下进入apidoc目录，点击Index.html，可以看到接口文档

　　也可以直接从浏览器中，通过url访问接口文档，地址为：http://127.0.0.1:8088/static/index.html，虽然设置的是apidoc目录，但也是通过静态文件配置的，所以，不能直接访问apidoc/index.html，而是需要访问static/index.html