使用apidoc编写golang接口文档

apidoc简述

•

apidoc基于nodejs,代码开源。

•

apidoc根据代码中以规范格式编写的注释，创建说明文档，文档为html格式，能够发布出去。

apidoc支持众多编程语言的文档生成：C#、Java、JavaScript、Python、Golang、Php等。

官网地址^[1]

github项目地址^[2]

apidoc安装

•检查本地是否有nodejs环境：node -v

•安装nodejs•下载^[3]•解压

•xz xxx.tar.xz•tar -xvf xxx.tar

•sudo ln -s usr/local/node/bin/node usr/local/bin/•sudo ln -s usr/local/node/bin/npm usr/local/bin/•切换npm镜像服务

•$ npm config set registry https://registry.npm.taobao.org/•npm config get registry

•检查是否已安装apidoc：apidoc -h

•npm install apidoc -g•sudo ln -s usr/local/node/bin/apidoc usr/local/bin/

apidoc使用

•

初始化apidoc.json

•

在项目根目录下创建apidoc.json文件，

•

apidoc.json内容实例

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1"
}

- 参数含义


  | 参数        | 说明                                                         |
  | ----------- | ------------------------------------------------------------ |
  | name        | 项目名称                                                     |
  | version     | 项目版本                                                     |
  | description | 项目描述                                                     |
  | title       | 浏览器标题                                                   |
  | url         | api路径前缀 会自动拼接到@api 路径前，可以设置为空串          |
  | sampleUrl   | 如果设置，将显示用于测试api方法（发送请求）的表单。有关详细信息，请参阅[@apiSampleRequest](http://apidocjs.com/#param-api-sample-request)。|
  | header      | api文档的头                                                  |
  | title       | 左侧导航栏中显示的文本                                       |
  | filename    | 内容文件，为md(markdown)格式，可以写前言等项目边角信息       |
  | footer      | 与header相同，只不过一个在头，一个在尾，不再赘述             |
  | title       |                                                              |
  | filename    |                                                              |
  | order       | 排序                                                         |

•

添加api注释

•

api注释是apidoc自定义的，用于生成文档的注释。

•

apidoc按注释快解析注释，两个注释快如下：

/**
 * @api {get} /user/{id}  获取用户信息
 */
/**
 * @api {put} /user/{id}  修改用户信息

apidoc仅解析含有@api或@apiDefine的注释块。一个注释块仅能有一个@apiDefine。

@apiGroup不支持中文，需要和@apiDefine配合使用来支持中文。

apidoc参数说明

| 参数 | 说明 | | :--------: | :----------------------------------------: | | @api | 定义api | | @apiDefine | 定义通用内容：请求参数、返回值、错误列表等 | | @apiGroup | api组属 | | @apiName | api名称 |

/**
*
* @api {get} /v1/user/list
* @apiDescription 用户列表
* @apiGroup User
* @apiName userlist
* @apiVersion 0.1.0
*
*
* @apiExample {curl} 访问示例：
* curl -i http://0.0.0.0:8765/v1/user/list/
*
* @apiSuccess (200) {Int} code StatueCode状态码.
* @apiSuccess (200) {String} message  Message提示信息.
* @apiSuccess (200) {Map} data  Data返回数据.
* @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "code": "200",
 *       "message": "success",
 *       "data":{}
 *     }
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 10020 Not Found
 *     {
 *        "code": "10020",
 *       "message": "fail",
 *     }


 */

.cs.dart.erl.go.java.js.php.py.rb.tsapidoc -f ".*\.js$" -f ".*\.ts$"

References

[1][2][3]