restful api 文档定义工具

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

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

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.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>
### Restful API 设计文档工具 设计 RESTful API 的过程中,良好的文档化是非常重要的。这不仅有助于开发人员理解如何使用 API,还能提高团队协作效率并减少沟通成本。以下是几种常用的 RESTful API 文档工具: #### 1. **Swagger (OpenAPI)** Swagger 是目前最流行的 RESTful API 文档工具之一。它基于 OpenAPI 规范,允许开发者定义 API 的结构并通过可视化界面展示其功能[^1]。Swagger 提供了多种工具支持整个 API 生命周期,包括设计、实现、测试和部署。 - Swagger Editor:在线编辑器,可以用来编写 OpenAPI 定义文件。 - Swagger UI:提供交互式的 API 文档页面,方便用户了解和调用接口。 - Swagger Codegen:自动生成客户端和服务端代码框架。 ```bash npm install -g swagger-cli swagger project edit my-api.yaml ``` #### 2. **Postman** Postman 不仅是一个强大的 API 测试工具,还提供了内置的文档生成功能。它可以记录请求历史并将这些请求转换为易于阅读的文档[^4]。此外,Postman 支持团队协作,使多人能够共同维护同一个 API 集合。 - Postman Collections:保存一组相关的 HTTP 请求及其参数配置。 - Documentation Generator:一键生成可共享的 API 文档链接。 ![Postman Example](https://www.postman.com/img/v1/social/postman.png) #### 3. **RAML (RESTful API Modeling Language)** RAML 是一种专门用于描述 RESTful API 的语言,具有简洁易读的特点。通过 RAML 文件,你可以清晰地表达资源路径、方法以及响应模式等内容[^2]。许多现代 IDE 和插件都支持解析 RAML 并渲染成图形化的形式。 ```yaml #%RAML 1.0 title: User Management System version: v1 baseUri: https://api.example.com/{version} /media: /images: post: description: Upload new image file. body: application/json: type: object properties: filename: string contentType: string ``` #### 4. **Apiary** Apiary 结合了 Blueprint 描述语法与云端托管服务,使得创建高质量的 API 文档变得简单快捷。Blueprint 类似于 Markdown,但增加了额外的关键字以便更精确地标记数据模型和行为逻辑[^3]。 > 注意:虽然 Apiary 曾经广受欢迎,但它已被停止更新,官方推荐迁移到其他替代方案比如 Stoplight 或 Insomnia。 --- ### 总结 每种工具都有自己的优势,在选择具体产品之前建议先评估项目需求和技术栈适配程度。如果追求标准化且广泛接受的标准,则优先考虑采用 Swagger/OpenAPI;而对于轻量级快速原型构建而言,RAML 可能更加合适一些。
评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

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

抵扣说明:

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

余额充值