restful api 文档定义工具

apidoc install

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>
  • 0
    点赞
  • 2
    收藏
    觉得还不错? 一键收藏
  • 1
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值