restful api 文档定义工具

apidoc install

Nodejs 安装

下载Windows Installer (.msi) 版本的进行安装

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  用户手机号
@ap
a18c
iParam {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>