apiDoc生成接口文档,不费吹灰之力
栏目: JavaScript · 发布时间: 5年前
内容简介:之前做前端的时候,后端同学仗着自己是老同志,不给我接口文档苦逼如我,需要拿着笔坐在他的旁边,听他口述写下需要的api接口url和参数等等
背景
之前做前端的时候,后端同学仗着自己是老同志,不给我接口文档
苦逼如我,需要拿着笔坐在他的旁边,听他口述
写下需要的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" * } */ 复制代码
以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持 码农网
猜你喜欢:- SpringBoot整合Swagger3生成接口文档
- Java WebService接口生成和调用 图文详解
- 推荐一个接口文档自动生成工具Swagger
- ????????Koa编写的微信小程序码生成接口
- hapi框架搭建记录(二):路由改造和生成接口文档
- Vivado HLS 生成AXI接口的IP核
本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们。
利用Python进行数据分析
Wes McKinney / 唐学韬 / 机械工业出版社 / 2013-11-18 / 89.00
【名人推荐】 “科学计算和数据分析社区已经等待这本书很多年了:大量具体的实践建议,以及大量综合应用方法。本书在未来几年里肯定会成为Python领域中技术计算的权威指南。” ——Fernando Pérez 加州大学伯克利分校 研究科学家, IPython的创始人之一 【内容简介】 还在苦苦寻觅用Python控制、处理、整理、分析结构化数据的完整课程?本书含有大量的实践案例,......一起来看看 《利用Python进行数据分析》 这本书的介绍吧!