ApiDoc YAPI Swagger 编写接口文档

ApiDoc

apidoc支持外部接口jsonUrl生成接口文档，支持html和markdown两种格式，可以使用Word转换为doc和pdf文档。一个静态的文档很漂亮的生成了，但是实际控制这个现实的是api_data.js和api_project.js。但是实际上的数据显示是由api_data.json和api_project.json这两个json文件。

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

安装apidocjs

npm i -f install apidoc -g

#npm install apidoc-markdown

查看是否安装成功

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
  }
}

<?php
/**
 * @apiDefine User 测试apiGroup名字
 */

/**
 * @api {get} ?m=content&c=api&a=user 得到用户信息
 *
 * @apiHeader {String} access-key Users unique access-key.
 *
 * @apiVersion 0.2.2
 *
 * @apiName getUser
 * @apiGroup User
 * @apiDescription 接口描叙，可以写多行.
 *
 * @apiParam {Number} id Users unique ID.
 * @apiSampleRequest off 
 */
 function find(){}
 ?>

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

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

/**
 * @api {patch,put} /user/:id  更新
 * @apiParam {String} [firstname]  可为空的参数.
 * @apiParam {bool}   sex          性别
 * @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.
 */

在apidoc.json中配置的 sampleUrl: "http://api.github.com"。发送API请求示例 

/**
 * @api {get} /user/:id
 * @apiSampleRequest /test
 */

这将发送API请求

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

请求参数示例

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

接口返回文档注释

* @apiSuccess {int} code 状态码
* @apiSuccess {String} message 消息
* @apiSuccess {Object} data 响应数据对象
* @apiSuccess {String} data.total 数据总数

指定header样例

/**
 * @api {get} /user/:id
 * @apiHeaderExample {json} Header-Example:
 *     {
 *       "Accept-Encoding": "Accept-Encoding: gzip, deflate"
 *     }
 */

指定接口返回值样例

/*
 * @apiSuccessExample {json} 返回样例:
 * {
 * "code": 200,
 * "message": "ok",
 * "data": {
 * "req_header": {
 * "total_pages": 30,
 * "page": 1,
 * "page_size": 10
 * },
 * "req_data": [
 * {
 * "id": "14054",
 * "call_id": "6555397404244537344",
 * "caller_num": "01086482580",
 * "called_num": "01086488907",
 * "caller_area_city": "北京",
 * "called_area_city": "北京",
 * "time_start": "2019-07-12 18:48:54",
 * "time_conn": "2019-07-12 18:48:54",
 * "time_hangup": "2019-07-12 18:49:13",
 * "call_type": "呼入",
 * "call_result": "接通",
 * "hangup_direction": "被叫",
 * "vcc_id": "57",
 * "agent_name": "联通有限公司"
 * }
 * ]
 * }
 * }
 * @apiErrorExample {json} 错误返回:
 * {
 * "code": 14695
 * "message": "数据出错",
 * "data":[]
 * }
 */

  

指定应该解析的文件类型

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

 整个目录生成文档

apidoc -i /path -o /public/apidoc/

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

Apidoc生成Markdown+PDF接口文档

1.安装apidoc-markdown 

apidoc-markdown是一个根据apidoc输出文件直接生成markdown文件的工具。首先我们需要安装该工具：

npm install apidoc-markdown -g

2.导出Markdown文档 

apidoc-markdown主要命令参数如下：

• 参数 描述
• -p, --path 指定apidoc生成的文档目录
• -o, --output 指定输出的markdown文件路径(包含文件名)
• -t, --template 指定生成markdown文件的模板文件(EJS模板文件)

apidoc-markdown -p apidoc -o doc_markdown.md

 以上命令为扫描apidoc文件夹下的所有文件然后生成doc_markdown.md文档。

3.Typora导出PDF接口文档 

既然markdown文件都有了，那么导出PDF文件不是更简单了。在这里，寡人推荐一个灰常好用的markdown离线编辑工具——Typora Typora是一款离线轻量Markdown编辑器，该工具非常简洁

但是直接导出的pdf文档可能有问题，因为导出的markdown文件中会存在html标签，导致生成的文档出现很多html标签，非常影响阅读。所以需要对markdown文件进行改造，删除下图示例中的所有html标签。

删除所有标签后，然后再使用typora生成pdf文档即可。

3.在线网站导出PDF接口文档

复制doc_markdown.md中的内容粘贴到 冷熊简历

YApi

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

特性

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

Swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。