ApiDoc接口文档生成

1、环境准备

安装node.js：https://segmentfault.com/a/1190000006694897

安装apidoc：http://build.iteye.com/blog/2334273

2、apidoc基础

@api {method} path [title]  只有使用@api标注的注释块才会在解析之后生成文档，

         title会被解析为导航菜单(@apiGroup)下的小菜单 

         method可以有空格，如{POSTGET}

@apiGroup  name  分组名称，被解析为导航栏菜单

@apiName  name  接口名称，在同一个@apiGroup下，名称相同的@api通过@apiVersion区分，否          者后面@api会覆盖前面定义的@api

@apiDescription  text  接口描述，支持html语法

@apiVersion verison  接口版本，major.minor.patch的形式

@apiIgnore[hint]  apidoc会忽略使用@apiIgnore标注的接口，hint为描述

@apiSampleRequest  url  接口测试地址以供测试，发送请求时，@apimethod必须为POST/GET等            其中一种

@apiDefine name [title] [description]  定义一个注释块(不包含@api)，配合@apiUse使用可以引入注          释块  在@apiDefine内部不可以使用@apiUse

@apiUse name  引入一个@apiDefine的注释块

@apiParam [(group)] [{type}] [field=defaultValue] [description]

@apiHeader [(group)] [{type}] [field=defaultValue] [description]

@apiError [(group)] [{type}]field[description]

@apiSuccess [(group)] [{type}]field[description]

         用法基本类似，分别描述请求参数、头部，响应错误和成功  group表示参数的分组，type表示类型(不能有空格)，入参可以定义默认值(不能有空格)

@apiParamExample [{type}] [title]example

@apiHeaderExample [{type}] [title]example

@apiErrorExample [{type}] [title]example

@apiSuccessExample [{type}] [title]example

用法完全一致，但是type表示的是example的语言类型example书写成什么样就会解析成什么样，所以最好是书写的时候注意格式化，(许多编辑器都有列模式，可以使用列模式快速对代码添加*号)

@apiPermission name  name必须独一无二，描述@api的访问权限，如admin/anyone

3、使用

项目的目录：/usr/local/openresty/nginx/html  

一、新建apidoc.json文件

{

"name" : "yuanbl",

"version": "1.0.0",

"title": "mydoc",

"description": "my first apidoc test"

}

二、新建ApiDoc.php文件（强烈建议这样做）

/**

* @apiDefine 2xx

* @apiSuccess (Success 200) {Number} status_code Status Code

* @apiSuccess (Success 200) {String} message  Message

* @apiSuccess (Success 200) {List} [data='undefined'] Data

*/

/**

* @apiDefine 200

* @apiSuccessExample {json} 200 Ok

* {

* "message": "OK",

* "status_code": 200,

* "data":{}

* }

*/

/**

* @apiDefine      4xx

* @apiError (Client errors 4xx) {Number} status_code Status Code

* @apiError (Client errors 4xx) {String} message Message

* @apiError (Client errors 4xx) {List}  [errors='undefined'] Errors

*/

/**

* @apiDefine 422

* @apiErrorExample {json} 422 Unprocessable Entity

* {

* "message": "参数不全或不合要求，请客户端开发人员先做验证再请求本接口，以避免无效请求。",

* "errors": {

* "order_code": [

* "The order code field is required."

* ],

* "order_type": [

* "The order type field is required."

* ],

* "predict_time": [

* "The predict time field is required."

* ]

* },

* "status_code": 422

* }

*/

/**

* @apiDefine 500

* @apiErrorExample {json} 500 Internal Server Error

* {

* "message": "服务器内部错误",

* "status_code": 500

* }

*/

 三、新建demo.php文件

/**

* @api              {GET}  http://192.168.248.128/engineers/{engineer_id}?token={token}  工程师信息查询 yuanbl1

* @apiGroup          engineers

* @apiVersion        2.0.0

* @apiDescription

* --------------------------------------

* 作者:yuanbl1

*

* 创建时间:2017-07-21

*

* email:[email protected]

*

* 备注:

*

* --------------------------------------

*

* @apiParam {Number} engineer_id 工程id

*

* @apiSuccess (返回字段:) {Number}  status_code 状态码

* @apiSuccess (返回字段:) {String}  message    提示信息

* @apiSuccess (返回字段:) {Json}    data        返回的数据包

* @apiSuccess (返回字段:) {String}  data.engineer_name 工程师姓名

* @apiSuccess (返回字段:) {String}  data.engineer_name 工程师编号

* @apiSuccess (返回字段:) {String}  data.name          工程师别名

* @apiSuccess (返回字段:) {String}  data.str          工程师描述

*

* @apiSuccessExample 成功1__时返回的数据:

* HTTP/1.1 200 Success

*  {

*      "status_code": 200,

*      "message": "OK",

*      "data":{

*          "engineer_name": "张三",

*          "engineer_code": "C16055"

*      }

* }

*

* @apiSuccessExample 成功2__时返回的数据:

* HTTP/1.1 200 Success

* {

*      "status_code": 200,

*      "message": "OK",

*      "data":{

*          "name":"hello",

*          "str" :"world"

*      }

* }

*

*

* @apiUse 200

* @apiUse 401

* @apiUse 422

* @apiUse 500

*/

四、生成

apidoc -i /usr/local/openresty/nginx/html/api/ -o /usr/local/openresty/nginx/html/apidoc/

参数说明：

原型：apidoc -f ".*\\.js$"-f".*\\.java$" -i myapp/ -o apidoc/ -t mytemplate/

-f 文件过滤

使用正则表达式，表示哪些文件需要本转换，不设置的情况下，默认为.cs .dart .erl .Go.Java.js.PHP.py .rb .ts 后缀的文件。

-i 代码文件夹

-o 输出Api文档的路径

-t 使用模板文件的路径，可以自定义输出的模板

常用的命令格式如下:

apidoc -i myapp /-o apidoc/

五、效果图

1

2

六、其他工具介绍

Swagger