效果
背景
之前做前端的时候, 后端同学仗着自己是老同志, 不给我接口文档
苦逼如我, 需要拿着笔坐在他的旁边, 听他口述
写下需要的 api 接口 url 和参数等等
现在自己做后端了, 那不能这样子胡作非为了
自己吃的苦, 怎能给其他同学吃呢?
这时候,apiDoc 你值得拥有, 稳稳的输出一篇优质的接口文档
安装 apidoc
官网上是全局安装, 我是喜欢安装到项目中, 这样可以在另一个环境下,npm install就可以下载有所有依赖包
npm install apidoc --save-dev/-D写注释
注册接口的注释
/**
* @api {post} /v1/auth/register User Register
* @apiName UserRegister
* @apiGroup userAuthentication
*
* @apiParam {String} username New user's username.
* @apiParam {String} password New user's password.
*
* @apiSuccess {String} username The username of the register user.
* @apiSuccess {string} message The registering success info.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "username": "username",
* "message": "User registered successful"
* }
*
* @apiError REGISTER_FAILURE The register failure.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 500 Internal Server Error
* {
* "err": "REGISTER_FAILURE",
* "message": "User register failure!"
* }
*/删除接口的注释
/**
* @api {delete} /v1/auth/user/ User delete
* @apiName UserDelete
* @apiGroup userAuthentication
*
* @apiParam {String} username User's username.
* @apiParam {String} executor Executor of this operation.
*
* @apiSuccess {String} username The username of the deleted user.
* @apiSuccess {string} message The message if deleting successful.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "username": "username",
* "message": "Delete User Successful"
* }
*
* @apiError NOT_LOGIN The register failure.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 401 Unauthorized
* {
* "err": "NOT_LOGIN",
* "message": "User has not logon in!"
* }
*/写入命令
将 apidoc -i routers/ 写入 package.json 的命令中
routers 文件夹下都是路由文件
"scripts": {
"test": "echo \"Error: no test specified\"&& exit 1",
"lint": "eslint .",
"apidoc": "apidoc -i routers/",
"dev": "node --harmony index.js"
},出现了{"message":"Done.","level":"info"}, 即成功了
执行命令
执行 npm run apidoc 即可拿到接口文档
这样, 在项目中就会出现 doc 文件夹
生成文档
这样,doc文件夹中包含该页面的所有材料
打开index.html
热乎乎的接口文档诞生了
结构解读
一个静态的文档很漂亮的生成了，但是实际控制这个方法的是 api_data.js 和 api_project.js。但是实际上的数据显示是由 api_data.json 和 api_project.json 这两个 json 文件。
所以在支持将其他 json 格式转换成 api_data.json 和 api_project.json，把 apidoc 生成的这两个文件进行替换，然后替换 js 文件，直接生产静态文档。
命令行界面
查看所有命令
apidoc -h| 选项 | 作用 |
|---|---|
| -f –file-filters | 用于选择应分析的文件的 regex 筛选器（可以使用多个 -f）。（默认值：[]） |
| -e, –exclude-filters | 用于选择不应解析的文件 / 目录的 regex 筛选器（可以使用 many-e）。（默认值：[]） |
| -i, –input | 输入 / 源目录名。（默认值：[]） |
| -o, –output | 输出目录。（默认：“./doc/”） |
| -t, –template | 对输出文件使用模板。（默认值：“/usr/local/lib/node_modules/apidoc/template/”） |
| -c, –config | 包含配置文件（apidoc.json）的目录路径。（默认值：“./”） |
| -p, –private | Include private APIs in output. |
| -v, –verbose | 详细调试输出。 |
| –debug | 显示调试消息。 |
| –color | 关闭日志颜色。 |
| –parse | 只解析文件并返回数据，不创建文件。 |
| –parse-filters | 可选的用户定义筛选器。格式名 = 文件名（默认值：[]） |
| –parse-languages | 可选的用户定义语言。格式名 = 文件名（默认值：[] |
| –parse-parsers | 可选的用户定义的分析器。格式名 = 文件名（默认值：[]） |
| –parse-workers | 可选的用户定义的工作人员。格式名 = 文件名（默认值：[]） |
| –silent | 关闭所有输出。 |
| –simulate | 执行但不写入任何文件。 |
| –markdown [markdown] | 关闭默认标记分析器或将文件设置为自定义分析器。（默认值：真） |
| –line-ending | 关闭自动检测行尾。允许值：lf，cr，crlf。 |
| –encoding | 设置源代码的编码。[UTF8]格式。（默认值：“utf8”） |
| -h, –help | 输出使用信息 |
所用的的 apiDoc 的参数(翻译)
@api
@api {method} path [title]必需的！
如果没有该指示器，apidoc 解析器将忽略文档块。
唯一的例外是 @apidefine 定义的文档块，它们不需要@api。
Usage: @api {get} /user/:id Users unique ID.
| Name | Description |
|---|---|
| method | Request method name: DELETE, GET, POST, PUT, … |
| path | Request Path. |
| title optional | A short title. (used for navigation and article header) |
/**
* @api {get} /user/:id
*/@apiName
@apiName name应始终使用。
定义方法文档块的名称。名称将用于生成的输出中的子导航。结构定义不需要 @apinname。
用法：@apinname getuser
| Name | Description |
|---|---|
| name | 方法的唯一名称。可以定义相同的名称和不同的@apiversion。格式：method+path（例如get+user），只有一个建议，您可以根据需要命名。也可以用作导航标题。 |
/**
* @api {get} /user/:id
* @apiName GetUser
*/@apiGroup
@apiGroup name应始终使用。
定义方法文档块所属的组。组将用于生成的输出中的主导航。结构定义不需要 @apigroup。
用法：@apigroup user
| Name | Description |
|---|---|
| name | 组名称。也使用导航标题。 |
/**
* @api {get} /user/:id
* @apiGroup User
*/@apiParam
@apiParam [(group)] [{type}] [field=defaultValue] [description]描述传递给 API 方法的参数。
用法：@apiparam（mygroup）number id users unique id。
| Name | Description |
|---|---|
| (group)optional | 所有参数都将按此名称分组。如果没有组，则设置默认参数。您可以使用 @apidefine 设置标题和说明。 |
| {type}optional | 参数类型, 如{Boolean}, {Number}, {String}, {Object}, {String[]}
|
| {type{size}}optional | 变量大小的信息{string{..5}} 最大值为 5 的字符串.{string{2..5}} 最小 2 最大为 5 的字符串.{number{100-999}} 在 100 到 999 的 i 数字. |
| {type=allowedValues}optional | 有关变量允许值的信息。{string="small"} 包含 small 的字符串,{string="small","huge"}包含 small/huge 的字符串,{number=1,2,3,99}一个允许值是 1,2,3, 和 99 的数字,{string {..5}="small","huge"}最多 5 个字符的字符串，只包含单词“small”或“mage”。 |
| field | 变量名称. |
| [field] | 带括号的 fieldname 将变量定义为可选变量。 |
| =defaultValueoptional | 参数默认值。 |
| descriptionoptional | 字段的说明。 |
/**
* @api {get} /user/:id
* @apiParam {Number} id Users unique ID.
*/
/**
* @api {post} /user/
* @apiParam {String} [firstname] Optional Firstname of the User.
* @apiParam {String} lastname Mandatory Lastname.
* @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.
*/@apiSuccess
@apiSuccess [(group)] [{type}] field [description]成功返回参数。
用法：@apiSuccess {String} firstname Firstname of the User。
| Name | Description |
|---|---|
| (group)optional | 所有参数都将按此名称分组。 |
如果没有组，则设置默认成功 200。
您可以使用 @apidefine 设置标题和说明。
{type}optional| 返回类型, 如{Boolean}, {Number}, {String}, {Object}, {String[]}
field| 返回标识符（返回成功代码）。
description optional| 字段的说明。
/**
* @api {get} /user/:id
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*/Example with (group), more group-examples at @apiSuccessTitle:
/**
* @api {get} /user/:id
* @apiSuccess (200) {String} firstname Firstname of the User.
* @apiSuccess (200) {String} lastname Lastname of the User.
*/Example with Object:
/**
* @api {get} /user/:id
* @apiSuccess {Boolean} active Specify if the account is active.
* @apiSuccess {Object} profile User profile information.
* @apiSuccess {Number} profile.age Users age.
* @apiSuccess {String} profile.image Avatar-Image.
*/Example with Array:
/**
* @api {get} /users
* @apiSuccess {Object[]} profiles List of user profiles.
* @apiSuccess {Number} profiles.age Users age.
* @apiSuccess {String} profiles.image Avatar-Image.
*/@apiSuccessExample
@apiSuccessExample [{type}] [title]
example成功返回消息的示例，输出为预先格式化的代码。
用途：` @apiSuccessExample {json} Success-Response:
{"content": "This is an example content"}`
| Name | Description |
|---|---|
| typeoptional | 响应格式 |
| titleoptional | 示例的简短标题 |
| example | 详细示例，支持多行 |
/**
* @api {get} /user/:id
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*/@apiError
@apiError [(group)] [{type}] field [description]成功返回参数。
用法：@apiError UserNotFound。
| Name | Description |
|---|---|
| (group)optional | 所有参数都将按此名称分组。如果没有组，则设置默认错误 4xx。您可以使用@apidefine 设置标题和说明。 |
| {type}optional | 返回类型, 如{Boolean}, {Number}, {String}, {Object}, {String[]}
|
| field | 返回标识符（返回失败代码）。 |
| description optional | 字段的说明。 |
/**
* @api {get} /user/:id
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*/@apiErrorExample
@apiErrorExample [{type}] [title]
example失败返回消息的示例，输出为预先格式化的代码。
用途：` @apiErrorExample {json} Error-Response:
This is an example. `
| Name | Description |
|---|---|
| typeoptional | 响应格式 |
| titleoptional | 示例的简短标题 |
| example | 详细示例，支持多行 |
/**
* @api {get} /user/:id
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/参考文献
apidoc 官网
接口文档神器之 apidoc
apidoc 快速生成在线文档，apidoc 生成静态文件的生成规则，原理分析，实践
- 欢迎大家进群, 参与讨论
- 一起进步, 是我们的准则, 我们是前端的一道美丽风景线
- 请加我的 vx：qiufeihong0203, 拉你进群
- 欢迎关注 feihong 的掘金账号。
- 原文地址。
版权声明
转载时请注明作者 qiufeihong 以及本文地址：http://www.qiufeihong.top/technical-summary/apiDoc/