Django项目生成api文档 之 apidoc（1）

一、安装apidoc

1.安装配置 Node.js

Step1：下载Node.js安装包

下载地址为：https://nodejs.org/en/download/

Step2：安装Node.JS

1）双击下载下来的安装包v12.13.1,点击运行，然后一路next （后面有遇到一个勾选框的页面，忽略，继续next）

2）默认安装目录为 “C:\Program Files\nodejs” , 本文将安装目录设置为 “ D:\Program Files\nodejs ”

Step3：检测安装

1）检测path配置

2）检测node.js和npm是否安装成功

Step4：配置npm

1）配置npm的全局模块的存放路径以及cache的路径

• 在安装目录（D:\Program Files\nodejs）下建立 “node_global” 及 “node_cache” 两个文件夹。
  
• 在cmd命令行中输入如下内容：
  npm config set prefix "D:\Program Files\nodejs\node_global"
npm config set cache "D:\Program Files\nodejs\node_cache"
  

2）配置镜像
输入命令npm config set registry=http://registry.npm.taobao.org 配置镜像站

3）查看配置结果
输入命令npm config list 显示所有配置信息

4）检测配置的镜像站

• 输入：npm config get registry
• 输入：Npm info vue ，查看能否获得vue的信息
  

注意：此时，默认的模块 D:\Program Files\nodejs\node_modules 目录
将会改变为 D:\Program Files\nodejs\node_global\node_modules 目录，暂时还看不出来，但是如果直接运行npm install等命令会报错的。

Step5：配置环境变量

1）增加环境变量NODE_PATH：D:\Program Files\nodejs\node_global\node_modules

2）在path环境变量中添加 D:\Program Files\nodejs\node_global

2.安装 apidoc

在 cmd 命令行 中输入：

npm install apidoc -g

这里的 -g是指安装到 global全局目录

二、使用apidoc生成api文档

1.配置环境

Step 1：新建django项目

Step 2：新建app应用

本文的app应用是apidoc/apps/project，创建app应用的方法参考之前的文章。

Step 3：配置apidoc自动生成文件的目录

1. 新建apidoc/static/docs目录：——作者用于存放自动生成的apidoc文件的目录
2. 将example下的apidoc.json、header.md和footer.md复制到此目录下。
   

Step 4：配置setting和urls

1. 配置setting
   
   
2. 配置url
   

Step 5：配置复制过来的apidoc.json文件

{
	  "name": "AutoTest API文档",
	  "version": "0.3.0",
	  "description": "Documentation for the REST api access provided at AutoTest",
	  "title": "AutoTest API文档",
	  "url" : "http://172.28.82.102:8000",
	  "sampleUrl": "https://apidoc.free.beeceptor.com",
	  "header": {
		    "title": "Introduction",
		    "filename": "header.md"
	  },
	  "footer": {
		    "title": "Best practices",
		    "filename": "footer.md"
	  },
	  "template": {
		    "withCompare": true,
		    "withGenerator": true,
		    "aloneDisplay": false
	  }
}

apidoc.json相关参数说明

参数	描述
name	apiDoc文档项目的大标题
version	apiDoc项目的版本
description	api文档的简介（大标题下的描述）
title	浏览器标题，即网页在浏览器中打开时，浏览器上方该页面的title
url	api路径的前缀

注意：

1. 复制过来的footer.md和header.md 产生了上图的Introduction 和 Best practices 部分。
2. footer.md 和header.md 使用 markdown 语法。

Step 6：配置api文档内容

1. 在 apps/project 目录下新建一个.py文件（本文新建了example.py和projectIndex.py）：一个文件一个api说明

2. example.py:

   """
   @api {post} /project/indexShow 获取project列表信息
   @apiVersion 0.3.0
   @apiName 获取查询的项目信息
   @apiGroup Project
   
   @apiParam {String} [name=''] 需查询的项目名
   @apiParam {Number} [page=1] 页码
   @apiParam {Number} [page_size=10] 每页容量
   @apiParamExample {json} Request-Example:
       {
           'name':'sunny',
           'page':1,
           'page_size':10
       }
   
   @apiSuccess (success 200)  {Number} code 结果码
   @apiSuccess (success 200) {String} msg 结果信息
   @apiSuccess (success 200) {json} data 查询返回结果
   @apiSuccess (success 200) {List} list 查询结果
   @apiSuccess (success 200) {Number} id 项目ID
   @apiSuccess (success 200) {String} name 项目名称
   @apiSuccess (success 200) {String} desc 项目描述
   @apiSuccess (success 200) {Datetime} create_time 项目创建时间
   @apiSuccess (success 200) {Datetime} modify_time 项目修改时间
   @apiSuccess (success 200) {Boolean} is_delete 项目是否已删除
   @apiSuccess (success 200) {Number}  count 记录数
   
   @apiExample {curl} Example usage:
       curl -i http://172.28.82.102:8000/project/indexShow
   @apiSuccessExample {json} Success-Response:
   HTTP/1.1 200 OK
      {
       "code":0,
       "msg":"成功",
       "data":{
           "list": [ {
                       "id": 6,
                       "name": "xxx",
                       "desc": "xxx",
                       "status": true,
                       "create_time": "2019-10-30 11:02:18",
                       "modify_time": "2019-10-31 09:44:15",
                       "is_delete": false
                   },
                   {
                       "id": 1,
                       "name": "xxx",
                       "desc": "xxx",
                       "status": true,
                       "create_time": "2019-10-24 14:27:30",
                       "modify_time": "2019-12-11 09:31:50",
                       "is_delete": false
                   }],
           "count":2
       }
      }
   @apiSampleRequest http://172.28.82.102:8000/project/indexShow
   """
   

3. projectIndex.py 内容类似

2.生成apidoc的相关文件

在static/docs文件夹下面执行命令： apidoc -i 要参考的注释文档所在地址(包含注释信息的.py文件) -o 输出位置(自动产生文件的位置)
-i 生成文件夹下面代码所有的注释

3.查看结果

在浏览器中输入：http://127.0.0.1:8000/docs/index.html

---

[参考链接]：

node.js的安装：
[1]：https://www.php.cn/js-tutorial-414607.html
[2]：https://www.runoob.com/nodejs/nodejs-install-setup.html

Python-Django使用apidoc接口文档
[1]：https://blog.csdn.net/weixin_40475396/article/details/80352744
[2]：https://apidocjs.com（官网）