apidoc install
Nodejs 安装
Nodejs 全局变量设置
在安装目录下创建 node_global 和 node_cache 文件夹
npm config set prefix "C:\Program Files\nodejs\node_global"
npm config set cache "C:\Program Files\nodejs\node_cache"
Nodejs 系统环境变量设置:
- 新建变量
NODE_PATH
值为C:\Program Files\nodejs\node_global\node_modules
- 编辑
PATH
添加C:\Program Files\nodejs\node_global
- 新建变量
apidoc 安装
npm install apidoc -g
Demo
Demo 定义
- 创建API文档目录结构
- app # APP的 api定义目录
- apidoc.json # 文档配置
- api.py # API 定义 (可以定义多个文件)
- header.md # 页头定义
- appdoc # 文档生成目录
apidoc.json
定义
{
"name": "接口文档",
"version": "0.1.0",
"title": "Custom apiDoc browser title",
"url" : "https://www.xxxx.com/app/webchat/api/v1",
"header": {
"title": "页头",
"filename": "header.md"
}
}
api.py
定义
# -*- encoding:utf8 -*-
"""
author: quanbin_zhu
time : 2018/1/4 18:04
"""
"""
@api {post} /auth/login login
@apiGroup Auth
@apiVersion 0.1.0
@apiExample {curl} 示例:
curl -H "Content-Type:application/json"
-d '{"wx-code":"value", "wx-session-id":"value"}'
-X POST http://{url_prefix}/auth/login
@apiName Login
@apiHeader {String} Content-Type application/json
@apiDescription 微信小程序登录认证
@apiParam {String} wx-code 微信登录 code
@apiParam {String} wx-session-id 若缓存中存在SESSION ID, 则传入该参数
@apiSuccess (登录成功) {String} status 登录状态
@apiSuccess (登录成功) {String} wx-session-id 有效的 SESSION ID
@apiSuccessExample Login-Success-Response:
HTTP/1.1 200 OK
{
"status": "ok",
"wx-session-id": "Fyy48ARghOohwYr033SO3aS0zKenpr6x3qGkQdu9hAIP0WwuIE4J60Cqeo4"
}
@apiError (登录失败) {String} errmsg 登录失败原因
@apiErrorExample Login-Error-Response:
HTTP/1.1 200 OK
{
"status": "no",
"errmsg": "没有小程序访问权限!"
}
"""
"""
@api {post} /auth/register register
@apiGroup Auth
@apiVersion 0.1.0
@apiExample {curl} 示例:
curl -H "Content-Type:application/json"
-d '{"wx-code":"value", "wx-user-name":"tom", "wx-user-phone":"18700000000", "wx-user-activate-code":"9hAIP0WwuIE4J60"}'
-X POST http://{url_prefix}/auth/register
@apiName Register
@apiHeader {String} Content-Type application/json
@apiDescription 微信小程序用户注册认证
@apiParam {String} wx-code 微信登录 code
@apiParam {String} wx-user-name 用户姓名
@apiParam {String} wx-user-phone 用户手机号
@apiParam {String} wx-user-activate-code 用户激活码
@apiSuccess (注册成功) {String} status 注册状态
@apiSuccess (注册成功) {String} wx-session-id 有效的 SESSION ID
@apiSuccessExample Login-Success-Response:
HTTP/1.1 200 OK
{
"status": "ok",
"wx-session-id": "Fyy48ARghOohwYr033SO3aS0zKenpr6x3qGkQdu9hAIP0WwuIE4J60Cqeo4"
}
@apiError (注册失败) {String} errmsg 登录失败原因
@apiErrorExample Login-Error-Response:
HTTP/1.1 200 OK
{
"status": "no",
"errmsg": "激活码已被使用!"
}
"""
header.md
定义
- 作者: borey.zhu
- 博客: [ice泉](http://blog.csdn.net/agony__x)
- 时间: 2018-01-05
Demo 编译
# 可以使用 -t 指定 template, 不填使用默认的template, 可以使有 apidoc -h 查看
apidoc -i ./app -o ./apidoc
Demo 效果
打开 apidoc 目录下的 index.html
隐藏下标
修改 template 下的 index.html文件
<script id="template-generator" type="text/x-handlebars-template">
{{#if template.withGenerator}}
{{#if generator}}
// 隐藏下标题
<div style="display:none;" class="content">
{{__ "Generated with"}} <a href="{{{generator.url}}}">{{{generator.name}}}</a> {{{generator.version}}} - {{{generator.time}}}
</div>
{{/if}}
{{/if}}
</script>