目录
- 前言
- apidoc的安装
- Python文件定义接口信息
- apidoc.json文件
- 生成apidoc网页文件
前言
- 操作系统win10
- 时间2019年02月
- Python版本:Python 3.5.2
- Nodejs版本:node v8.9.3
- 参考网址1
- 参考网址2
- 参考网址3
apidoc的安装
npm install apidoc -g
-g参数表示全局安装,这样哪儿都能用了哦
Python文件定义接口信息
在对应的函数添加apidoc接口的定义描述,包括但不限于以下代码
def login():
"""
@api {POST} http://127.0.0.1:8000/login/ 登录操作
@apiVersion 0.0.1
@apiName login
@apiGroup User
@apiDescription 这里可以描述一下这个函数的具体操作
这一行也是可以描述的
@apiParam {String} name 姓名
@apiParam {String} password 密码
@apiSuccess {Object} status 状态码
@apiSuccess {Object} msg 简略描述
@apiSuccessExample Response-Success:
HTTP 1.1/ 200K
{
'status': 0,
'msg': 'success'
}
@apiErrorExample Response-Fail:
HTTP 1.1/ 404K
{
'status': 1,
'msg': 'Fail'
}
"""
pass
def index():
"""
@api {GET} http://127.0.0.1:8000/index/ 主页操作
@apiVersion 0.0.1
@apiName index
@apiGroup User
@apiDescription 这里可以描述一下这个函数的具体操作
这一行也是可以描述的
@apiParam {Data} name 姓名
@apiSuccess {Object} status 状态码
@apiSuccess {Object} msg 简略描述
@apiSuccessExample Response-Success:
HTTP 1.1/ 200K
[
{
'id': 1,
'name': '张三'
},
{
'id': 2,
'name': '李四'
},
{
'id': 3,
'name': '王五'
}
]
@apiErrorExample Response-Fail:
HTTP 1.1/ 404K
{
'status': 1,
'msg': 'Fail'
}
"""
pass
apidoc.json文件
栗子1
{
"name": "我的apidoc示例",
"version": "0.0.1",
"description": "这是一句描述,描述了api文档",
"title": "API DOC EXAMPLE"
}
栗子2
这种栗子中需要在apidoc.json文件的当前路径下分别新建header.md和footer.md文件
apidoc.json
{
"name": "example",
"version": "0.1.0",
"description": "apidoc test1",
"header": {
"title": "这不是头",
"filename": "header.md"
},
"footer": {
"title": "这不是尾",
"filename": "footer.md"
}
}
header.md
# Example text from header.md
This text is from file "header.md".
##
In your projects "package.json" you can set "apidoc.header" with a title and a filename to include this file into your documentation.
This example attempts to integrate "header.md" and "footer.md".
{
"name": "example",
"version": "0.3.0",
"description": "apidoc example project.",
"apidoc": {
"header": {
"title": "My own header title",
"filename": "header.md"
},
"footer": {
"title": "My own footer title",
"filename": "footer.md"
}
}
}
footer.md
# Example text from footer.md
This text is from file "footer.md".
## HowTo include
Watch header.md for further information.
生成apidoc网页文件
apidoc -i 代码所在路径 -o 生成文件的路径
此时会在指定的生成文件路径中生成一个apidoc的文件夹,里面的index.html文件就是啦啦啦啦~~~