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 用户手机号 @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
restful api 文档定义工具_第1张图片

隐藏下标

修改 template 下的 index.html文件


                    
                    

你可能感兴趣的:(python,tools)