apiDoc生成接口文档,不费吹灰之力

栏目: JavaScript · 发布时间: 4年前

内容简介:之前做前端的时候,后端同学仗着自己是老同志,不给我接口文档苦逼如我,需要拿着笔坐在他的旁边,听他口述写下需要的api接口url和参数等等
apiDoc生成接口文档,不费吹灰之力

背景

之前做前端的时候,后端同学仗着自己是老同志,不给我接口文档

苦逼如我,需要拿着笔坐在他的旁边,听他口述

写下需要的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"} ,即成功了

apiDoc生成接口文档,不费吹灰之力

执行命令

执行 npm run apidoc 即可拿到接口文档

这样,在项目中就会出现 doc 文件夹

apiDoc生成接口文档,不费吹灰之力

生成文档

这样, doc 文件夹中包含该页面的所有材料

apiDoc生成接口文档,不费吹灰之力

打开 index.html

apiDoc生成接口文档,不费吹灰之力

热乎乎的接口文档诞生了

apiDoc生成接口文档,不费吹灰之力

结构解读

一个静态的文档很漂亮的生成了,但是实际控制这个方法的是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"
 *     }
 */
复制代码

以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持 码农网

查看所有标签

猜你喜欢:

本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们

七周七语言

七周七语言

Bruce A.Tate / 巨成、戴玮、白明 / 人民邮电出版社 / 2012-5-8 / 59.00元

内容简介: 从计算机发展史早期的Cobol、Fortran到后来的C、Java,编程语言的家族不断壮大。除了这些广为人知的语言外,还涌现了Erlang、Ruby等后起之秀,它们虽被喻为小众语言,但因其独特性也吸引了为数不少的追随者。 Bruce A. Tate是软件行业的一名老兵,他有一个宏伟目标:用一本书的篇幅切中要害地探索七种不同的语言。本书就是他的成果。书中介绍了Ruby、Io、......一起来看看 《七周七语言》 这本书的介绍吧!

JSON 在线解析
JSON 在线解析

在线 JSON 格式化工具

在线进制转换器
在线进制转换器

各进制数互转换器

HEX CMYK 转换工具
HEX CMYK 转换工具

HEX CMYK 互转工具