文章目录
一、安装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自动生成文件的目录
- 新建
apidoc/static/docs
目录:——作者用于存放自动生成的apidoc文件的目录 - 将example下的
apidoc.json
、header.md
和footer.md
复制到此目录下。
Step 4:配置setting和urls
- 配置setting
- 配置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路径的前缀 |
注意:
- 复制过来的footer.md和header.md 产生了上图的
Introduction
和Best practices
部分。 - footer.md 和header.md 使用 markdown 语法。
Step 6:配置api文档内容
-
在 apps/project 目录下新建一个.py文件(本文新建了
example.py
和projectIndex.py
):一个文件一个api说明 -
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 """
-
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(官网)