nodejs下的apidoc 帮助接口文档生成

其他 2018-06-22 16:13:27 阅读次数: 4
在项目开发过程中，总会牵扯到接口文档的设计与编写，之前使用的都是office工具，写一个文档，总也是不够漂亮和直观。好在git上的开源大神提供了生成文档的工具，so来介绍一下！
该工具是Nodejs的模块，请务必在使用前安装好nodejs环境！
工具名称：apiDoc
项目地址： http://apidocjs.com/
apoDoc是从源码的注释中生成RestFul api 文档，样子还是蛮漂亮的……
自己写了的ApiDoc文档自动生成工具，避免每次写完后手动执行生成代码
支持的注释样式:
JavaDoc-Style
/**
* This is a comment.
*/
  • 1
  • 2
  • 3
CoffeeScript
###
This is a comment.
###
  • 1
  • 2
  • 3
Elixir
@apidoc """
This is a comment.
"""
  • 1
  • 2
  • 3
Erlang（%不是必须的）
%{% This is a comment.%}
  • 1
  • 2
  • 3
Perl (Doxygen)
#**# This is a comment.#*
  • 1
  • 2
  • 3
Python
"""
This is a comment.
"""
  • 1
  • 2
  • 3
Ruby
=begin
This is a comment.
=end
  • 1
  • 2
  • 3
安装apiDoc
npm install apidoc -g
  • 1
使用npm命令安装apidoc即可！
使用方式:
在命令行中输入
apidoc -f ".*\\.js$" -f ".*\\.java$" -i myapp/ -o apidoc/ -t mytemplate/
  • 1
参数说明：
-f 文件过滤
使用正则表达式，表示哪些文件需要本转换，不设置的情况下，默认为.cs .dart .erl .go .java .js .php .py .rb .ts 后缀的文件。
-i 代码文件夹
-o 输出Api文档的路径
-t 使用模板文件的路径，可以自定义输出的模板
常用的命令格式如下:
apidoc -i myapp/ -o apidoc/
  • 1
配置
无package.json文件时，需要在代码文件夹的根目录下，创建apidoc.json文件。
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
在该文件中即可配置apidoc
有package.json文件时，在package.json文件中添加”apidoc”: { }属性即可。
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"apidoc": {
"title": "Custom apiDoc browser title",
}
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
配置属性如下:
name：项目名称
version：项目版本
description：项目介绍
title：浏览器显示的标题内容
url：endpoints的前缀，例如 https://api.github.com/v1
sampleUrl：如果设置了，则在api文档中出现一个测试用的from表单
header
title：导航文字包含header.md文件
filename：markdown-file 文件名
footer
title：导航文字包含header.md文件
filename：markdown-file 文件名
order：用于配置输出 api-names/group-names 排序，在列表中的将按照列表中的顺序排序，不在列表中的名称将自动显示。
模板的配置:
在apidoc.json中或在package.json中添加template属性，将对模板进行特殊设置
forceLanguage：生成指定语言的文档，简体中文仅需设置”zh-cn”，支持的语言： https://github.com/apidoc/apidoc/tree/master/template/locales
withCompare：是否启用与旧版本的比较功能，默认为true
withGenerator：是否输出生成信息，默认为true
jQueryAjaxSetup：设置Ajax请求的默认值,参见 http://api.jquery.com/jquery.ajaxsetup/
我使用的配置如下:
{
"name": "测试",
"version": "0.0.1",
"description": "API文档测试",
"title": "API文档测试",
"url" : " http://xxxxxxx",
"sampleUrl" : " http://xxxxxxxx",
"template":{
"forceLanguage":"zh-cn"
}
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
先来个demo试试：
在myapp文件夹下创建example.java
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
之后执行
apidoc -i myapp/ -o apidoc/
  • 1
打开apidoc文件夹下的index.html即可看到效果。赞赞哒……
重头戏来了，下面要讲解一下apiDoc的注释都是什么含义
@api
@api {method} path [title]
  • 1
使用该注释的才能被识别成为文档的一块内容
path：请求路径
title(可选)：标题
Example:
/**
* @api {get} /user/:id
*/
  • 1
  • 2
  • 3
@apiDefine
@apiDefine name [title]
[description]
  • 1
  • 2
定义重复内容，供其他模块引用
name：重复模块名
title（可选）：标题
description（可选）：说明
Example1:
/**
* @apiDefine MyError
* @apiError UserNotFound The <code>id</code> of the User was not found.
*/

/**
* @api {get} /user/:id
* @apiUse MyError
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
Example2:
/**
* @apiDefine admin User access only
* This optional description belong to to the group admin.
*/

/**
* @api {get} /user/:id
* @apiPermission admin
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
@apiDescription
@apiDescription text
  • 1
设置多行说明
text：多行说明内容
Example
/**
* @apiDescription This is the Description.
* It is multiline capable.
*
* Last line of Description.
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
@apiError
@apiError [(group)] [{type}] field [description]
  • 1
请求错误参数
（group）（可选）：参数将以这个名称分组，不设置的话，默认是Error 4xx
{type}（可选）：返回值类型，例如：{Boolean}, {Number}, {String}, {Object}, {String[]}
field：返回值字段名称
descriptionoptional（可选）：返回值字段说明
Example:
/**
* @api {get} /user/:id
* @apiError UserNotFound The <code>id</code> of the User was not found.
*/
  • 1
  • 2
  • 3
  • 4
@apiErrorExample
@apiErrorExample [{type}] [title]
example
  • 1
  • 2
错误返回信息样例。
type（可选）：返回内容的格式
title（可选）：标题
example：样例，可以是多行文本
Example:
/**
* @api {get} /user/:id
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
@apiExample
@apiExample [{type}] title
example
  • 1
  • 2
请求Api的测试样例
{type}（可选）：请求方式类型
title：标题
example：样例，可以是多行文本
Example:
/**
* @api {get} /user/:id
* @apiExample {curl} Example usage:
*/
  • 1
  • 2
  • 3
  • 4
  • 5
@apiGroup
@apiGroup name
  • 1
定义Api的分组
name：组名称，也是导航的标题
Example:
/**
* @api {get} /user/:id
* @apiGroup User
*/
  • 1
  • 2
  • 3
  • 4
@apiHeader
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
  • 1
定义head参数
(group)（可选）：分组
{type}（可选）：类型，例如：{Boolean}, {Number}, {String}, {Object}, {String[]}
field：变量名
[field]：定义变量，并标记变量是可选项
=defaultValue（可选）：默认值
description（optional）：变量说明
Examples:
/**
* @api {get} /user/:id
* @apiHeader {String} access-key Users unique access-key.
*/
  • 1
  • 2
  • 3
  • 4
@apiHeaderExample
@apiHeaderExample [{type}] [title]
example
  • 1
  • 2
head参数样例
{type}（可选）：请求方式类型
title：标题
example：样例，可以是多行文本
Example:
/**
* @api {get} /user/:id
* @apiHeaderExample {json} Header-Example:
* {
* "Accept-Encoding": "Accept-Encoding: gzip, deflate"
* }
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
@apiIgnore
@apiIgnore [hint]
  • 1
忽略不发布到文档
hint（可选）：不发布的原因
Example:
/**
* @apiIgnore Not finished Method
* @api {get} /user/:id
*/
  • 1
  • 2
  • 3
  • 4
@apiName
@apiName name
  • 1
定义api名称
name：api名称
Example:
/**
* @api {get} /user/:id
* @apiName GetUser
*/
  • 1
  • 2
  • 3
  • 4
@apiParam
@apiParam [(group)] [{type}] [field=defaultValue] [description]
  • 1
定义请求Api的参数
(group)（可选）：分组
{type}（可选）：类型，例如：{Boolean}, {Number}, {String}, {Object}, {String[]}
{type{size}}（可选）：类型限定长度，例如：{string{..5}} 限定最大长度为5个字符
{string{2..5}} 限定最短2个字符，最长5个字符
{number{100-999}} 限定数字在100-999之间
{type=allowedValues}（可选）：类型限定值，例如：{string=”small”}限定只允许传递small字符，
{string=”small”,”huge”} 限定只允许传递small或huge字符，
{number=1,2,3,99} 限定只允许传1，2，3，99这四个数字
field：变量名
[field]：定义变量，并标记变量是可选项
=defaultValue（可选）：默认值
description（optional）：变量说明
Examples:
/**
* @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.
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
@apiParamExample
@apiParamExample [{type}] [title]
example
  • 1
  • 2
请求参数样例
{type}（可选）：请求方式类型
title：标题
example：样例，可以是多行文本
Example:
/**
* @api {get} /user/:id
* @apiParamExample {json} Request-Example:
* {
* "id": 4711
* }
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
@apiPermission
@apiPermission name
  • 1
定义接口权限
name：权限名称
Example:
/**
* @api {get} /user/:id
* @apiPermission none
*/
  • 1
  • 2
  • 3
  • 4
@apiSampleRequest
@apiSampleRequest url
  • 1
设置测试请求form，如果在apidoc.json或package.json中设置过了sampleUrl，则默认请求地址为，sampleUrl+apipath，设置这个标签则重写测试请求路径
url：测试地址，
样例
@apiSampleRequest http://www.example.com 改变测试地址
@apiSampleRequest /my_test_path 在apipath中加前缀
@apiSampleRequest off 不显示测试请求from
Examples:
默认请求的地址是 http://api.github.com/user/:id
Configuration parameter sampleUrl: " http://api.github.com"/**
* @api {get} /user/:id
*/
  • 1
  • 2
  • 3
  • 4
需要将测试地址修改为 http://test.github.com/some_path/user/:id，则
Configuration parameter sampleUrl: " http://api.github.com"/**
* @api {get} /user/:id
* @apiSampleRequest http://test.github.com/some_path/
*/
  • 1
  • 2
  • 3
  • 4
  • 5
当地址需要请求 http://api.github.com/test/user/:id则
Configuration parameter sampleUrl: " http://api.github.com"/**
* @api {get} /user/:id
* @apiSampleRequest /test
*/
  • 1
  • 2
  • 3
  • 4
  • 5
不需要测试请求from
Configuration parameter sampleUrl: " http://api.github.com"/**
* @api {get} /user/:id
* @apiSampleRequest off
*/
  • 1
  • 2
  • 3
  • 4
  • 5
没有设置sampleUrl时需要显示测试请求from，并设置请求 http://api.github.com/some_path/user/:id
Configuration parameter sampleUrl is not set
/**
* @api {get} /user/:id
* @apiSampleRequest http://api.github.com/some_path/
*/
  • 1
  • 2
  • 3
  • 4
  • 5
@apiSuccess
@apiSuccess [(group)] [{type}] field [description]
  • 1
请求成功返回的参数
（group）（可选）：参数将以这个名称分组，不设置的话，默认是Error 4xx
{type}（可选）：返回值类型，例如：{Boolean}, {Number}, {String}, {Object}, {String[]}
field：返回值字段名称
descriptionoptional（可选）：返回值字段说明
Example:
/**
* @api {get} /user/:id
* @apiSuccess (200) {String} firstname Firstname of the User.
* @apiSuccess (200) {String} lastname Lastname of the User.
*/
  • 1
  • 2
  • 3
  • 4
  • 5
@apiSuccessExample
@apiSuccessExample [{type}] [title]
example
  • 1
  • 2
请求成功返回数据样例
{type}（可选）：请求方式类型
title：标题
example：样例，可以是多行文本
Example:
/**
* @api {get} /user/:id
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
@apiUse
@apiUse name
  • 1
使用在@apiDefine中定义的内容
name：在@apiDefine定义的name
Example:
/**
* @apiDefine MySuccess
* @apiSuccess {string} firstname The users firstname.
* @apiSuccess {number} age The users age.
*/

/**
* @api {get} /user/:id
* @apiUse MySuccess
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
@apiVersion
@apiVersion version
  • 1
设定Api的版本号
version：版本号，格式(major.minor.patch)
Example:
/**
* @api {get} /user/:id
* @apiVersion 1.6.2
*/
  • 1
  • 2
  • 3
  • 4
以上就是apiDoc的介绍！谢谢各位看官……
附上一个样例
user.java
/**
* @api {POST} /register 注册用户
* @apiGroup Users
* @apiVersion 0.0.1
* @apiDescription 用于注册用户
* @apiParam {String} account 用户账户名
* @apiParam {String} password 密码
* @apiParam {String} mobile 手机号
* @apiParam {int} vip = 0 是否注册Vip身份 0 普通用户 1 Vip用户
* @apiParam {String} [recommend] 邀请码
* @apiParamExample {json} 请求样例：
* ?account=sodlinken&password=11223344&mobile=13739554137&vip=0&recommend=
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
* @apiSuccessExample {json} 返回样例:
* {"code":"0","msg":"注册成功"}
*/

/**
* @api {POST} /login 用户登录
* @apiGroup Users
* @apiVersion 0.0.1
* @apiDescription 用于用户登录
* @apiParam {String} userName 用户名
* @apiParam {String} password 密码
* @apiParamExample {json} 请求样例：
* ?userName=张三&password=11223344
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {String} code 0 代表无错误 1代表有错误
* @apiSuccess (200) {String} user 用户信息
* @apiSuccess (200) {String} userId 用户id
* @apiSuccessExample {json} 返回样例:
* {"code":"0","msg":"登录成功","userId":"fe6386d550bd434b8cd994b58c3f8075"}
*/

/**
* @api {GET} /users/:id 获取用户信息
* @apiGroup Users
* @apiVersion 0.0.1
* @apiDescription 获取用户信息
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
* @apiSuccess (200) {String} name 真实姓名
* @apiSuccess (200) {String} mobile 手机号
* @apiSuccess (200) {String} birthday 生日
* @apiSuccess (200) {String} email 邮箱
* @apiSuccess (200) {String} summary 简介
* @apiSuccess (200) {String} recommendCode 我的推荐码
* @apiSuccess (200) {String} idCardNo 身份证号
* @apiSuccess (200) {String} memberState 会员状态 0普通用户 1VIP 2账户冻结
* @apiSuccess (200) {String} address 家庭住址
* @apiSuccess (200) {String} money 账户现金
* @apiSuccessExample {json} 返回样例:
* {
* "code": 0,
* "msg": "",
* "name": "真实姓名",
* "mobile": 15808544477,
* "birthday": "1990-03-05",
* "email": "[email protected]",
* "summary": "简介",
* "recommendCode": "我的推荐码",
* "idCardNo": "身份证号",
* "memberState": 1,
* "address": "家庭住址",
* "money": "30.65"
* }
*/


/**
* @api {POST} /users/:id 修改(完善)用户信息
* @apiGroup Users
* @apiVersion 0.0.1
* @apiDescription 修改(完善)用户信息
* @apiParam (200) {String} [name] 真实姓名
* @apiParam (200) {String} [mobile] 手机号
* @apiParam (200) {String} [birthday] 生日
* @apiParam (200) {String} [email] 邮箱
* @apiParam (200) {String} [summary] 简介
* @apiParam (200) {String} [idCardNo] 身份证号
* @apiParam (200) {String} [address] 家庭住址
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
* @apiSuccessExample {json} 返回样例:
* {"code":"0","msg":"修改成功"}
*/

猜你喜欢

转载自blog.csdn.net/weixin_38079422/article/details/78973660
今日推荐
TIOBE 5 月榜单：Fortran “复活”进入 Top 10
GCC 14.1 发布
面壁智能发布 Eurux-8x22B 开源大模型 —— 堪称「理科状元」
开源日报 | 谷歌扶持鸿蒙上位；开源Rabbit R1；Docker加持的安卓手机；微软的焦虑和野心；海尔电器把开放平台关了
中国码农的“35岁魔咒”
蘭雅 CorelDRAW 插件 2024.5.1 国际劳动节版，免费下载
Arc Browser for Windows 1.0 正式 GA
90后程序员开发视频搬运软件、不到一年获利超 700 万，结局很刑！
周排行
Java自定义时间格式
同步整形电路
在开发中最最最常用的字符串的属性大集合
Linux 查看端口占用并杀掉
Java基础四：ArrayList
多线程之死锁就是这么简单
mysql 基础命令集
awk 命令详解
Centos6.3编译安装nginx+php步骤
OCR （Optical Character Recognition，光学字符识别）
每日归档
更多
2024-05-08(42)
2024-05-07(14)
2024-05-06(40)
2024-05-05(0)
2024-05-04(7)
2024-05-03(19)
2024-05-02(0)
2024-05-01(4)
2024-04-30(1)
2024-04-29(40)

代码天地 © 2018 codetd.com

境外服务器   最新电视剧2022