全局下载 apidoc
npm i -g apidoc
项目根目录配置 apidoc.json
{
"name": "blog",
"version": "1.0.0",
"description": "blog项目API文档",
"title": "blog API",
"url" : "http://localhost:3000",
"sampleUrl": "http://localhost:3000",
"forceLanguage":"zh-cn",
"template": {
"withCompare": true,
"withGenerator": true
}
}
简单介绍下：
name, version, description
这三个配置项的内容会显示在生成文档的最上方，其中name即整个文档的大标题。title
网页的标题，显示在浏览器标签上。url
文档中每个API地址的前缀。sampleUrl
当有此项时，每个API文档的最后会有Sample Request测试部分。该配置项是测试API地址的前缀。-
header, footer
页面的头和尾。当多个页面都有相同的头和尾时，这个配置项就非常有用。子配置项中- title
页面左边菜单栏中显示的标题。 - filename
指向页头或页尾的模板文件，apiDoc使用的是Markdown文件。
- title
-
template
- withCompare
生成的文档有版本比较功能。后面会介绍。默认为”true”。 - withGenerator
生成的文档页尾带有一段文字，表示这个文档是由apiDoc生成的，加上这个代表对作者的尊重吧。默认为”true”。
- withCompare
接口文件api注释
比如我的接口文件在 router/user.js
*/
/**
* @api {get} /admin/user/reg 用户注册
* @apiName reg
* @apiGroup User
*
* @apiParam {String} us 用户账号
* @apiParam {String} ps 用户密码.
* @apiParam {Number} code 验证码.
*
* @apiSuccess {String} err Firstname of the User.
* @apiSuccess {String} msg Lastname of the User.
* @apiSampleRequest http://localhost:3000/admin/user/reg
* @apiVersion 1.0.0
*/
使用命令生成接口文档
apidoc -i router/ -o apidoc
如果 觉得太长可以配置
"scripts": {
"api":"apidoc -i router/ -o apidoc"
},
使用
npm run api
API文档注释
@api {get} /users/:user_id Request User Information
最主要的参数，{get}定义了HTTP请求是GET，API地址是/users/:user_id，文档中API的名称是Request User Information。@apiVersion 0.1.0
API的版本号，默认显示在API名称的右方。该参数可用来在不同的版本之间做比较，后面会介绍。@apiName GetUser
API名称，不影响文档。@apiGroup User
API分组名，文档内容中和菜单栏中同一组的API会在一同显示，方便阅读。@apiPermission admin
API的访问权限，文档中默认会API地址下面显示。没有权限要求的话，此项可以省略。@apiDescription API to get the user information.
API的详细描述，默认显示在API名称的下方。@apiExample Example usage:
API调用示例，该参数的下一行就是示例的内容，直到有空行结束。可以定义多个@apiExample，默认在文档中会以标签形式列出，标签名就是”Example usage:“。@apiParam {Number} user_id The user’s unique ID.
API参数字段介绍，”{Number}“定义了字段类型，”user_id”是字段名称，后面则是字段描述。可以定义多个@apiParam字段。@apiSuccess {String} name Name of the User.
API成功后返回的字段，如同@apiParam，”{String}“定义了字段类型，”name”是返回字段名称，后面则是字段描述。可以定义多个@apiSuccess字段。@apiSuccessExample {json} Success-Response:
显示一个API成功返回后Response响应的示例，”{json}“代表响应体是JSON类型。该参数的下行就是响应体内容，直到有空行结束。可以定义多个@apiSuccessExample，默认在文档中会以标签形式列出，标签名就是”Success-Response:“。@apiError UserNotFound User was not found.
API发生错误后的返回，”UserNotFound”是错误名称，后面则是错误描述。可以定义多个错误返回。@apiErrorExample {json} Error-Response:
显示一个API错误返回后Response响应的示例，”{json}“代表响应体是JSON类型。该参数的下行就是响应体内容，直到有空行结束。可以定义多个@apiErrorExample，默认在文档中会以标签形式列出，标签名就是”Error-Response:“。@apiSampleRequest http://localhost:5000/users/:user_id
文档提供的API Sample测试的地址。其实在”apidoc.json”中配过”sampleUrl”项后，此参数即可省去，除非这个API的测试URL比较特殊，需特别指定。
