restful api 文档定义工具

最新推荐文章于 2025-07-11 16:58:14 发布

原创最新推荐文章于 2025-07-11 16:58:14 发布 · 3k 阅读

2 ·

CC 4.0 BY-SA版权

文章标签：

#restful api

python 同时被 2 个专栏收录

4 篇文章

订阅专栏

tools

1 篇文章

订阅专栏

本文详细介绍Node.js的安装步骤及环境配置，并通过实例演示如何使用apidoc自动生成API文档，涵盖apidoc的安装与使用、API定义语法等关键内容。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

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 定义

- 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.youkuaiyun.com/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>