用ApiDoc YAPI编写接口文档

生成一个REST风格的Web API文档。

安装apidocjs

npm install apidoc -g

查看是否安装成功

apidoc -h

生成文档必须有.json 文件和带有Javadoc风格注释(可以在C#, Go, Dart, Java, JavaScript, PHP, TypeScript等语言中使用)的文件。

[root@centos php]# ls
apidoc.json  test.php

{
  "name": "apidoc-例子",
  "version": "0.3.0",
  "description": "apiDoc example project",
  "title": "apidoc-用户接口文档",
  "url": "https://[base_domain]/",
  "sampleUrl" : "https://[base_domain]/api/v1" //发送请求示例
  "order": [
    "getUser",
    "getList"
  ],
  "template": {
    "withCompare": true,
    "withGenerator": true
  }
}

然后直接运行命令apidoc, 然后会直接默认生成一个doc文件目录，当然可以指定一下（用i和o命令 即input和output）

/**
 * @api {get} /user/:id
 * @apiParam {Number} id Users unique ID.
 */

/**
 * @api {post} /user/
 * @apiParam {String} [firstname]  Optional Firstname of the User.
 * @apiParam {String} lastname     Mandatory Lastname.
 * @apiParam {String} country="DE" Mandatory with default value "DE".
 * @apiParam {Number} [age=18]     Optional Age with default 18.
 *
 * @apiParam (Login) {String} pass Only logged in users can post this.
 *                                 In generated documentation a separate
 *                                 "Login" Block will be generated.
 */

发送API请求示例 

在apidoc.json中配置的 sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest /test
 */

这将发送API请求

http://api.github.com/test/user/:id

请求参数示例

     * @apiParam {Number} agent_id 代理商ID
     * 
     * @apiParamExample {Number} agent_id
     * 10

指定应该解析的文件类型

apidoc -f ".*\\.(js|php)$" 

 整个目录生成文档

apidoc -i /path -o /path1/doc

只会生成含有apidoc注释的文件，更新apidoc注释后重新生成需要删除doc目录

 

YApi 是高效、易用、功能强大的 api 管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API，YApi 还为用户提供了优秀的交互体验，开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。

特性

• 基于 Json5 和 Mockjs 定义接口返回数据的结构和文档，效率提升多倍
• 扁平化权限设计，即保证了大型企业级项目的管理，又保证了易用性
• 类似 postman 的接口调试
• 自动化测试, 支持对Response断言 (可以利用该yapi的openapi与定时任务结合起来，进行定时的自动化测试)
• MockServer 除支持普通的随机 mock 外，还增加了 Mock 期望功能，根据设置的请求过滤规则，返回期望数据
• 支持 postman, har, swagger 数据导入
• 免费开源，内网部署，信息再也不怕泄露了