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:yuanbl1@qq.com
*
* 备注:
*
* --------------------------------------
*
* @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
网友评论