linux 使用apidoc 生成Restful web Api文档
官方文档:http://apidocjs.com/#example-basic
博客:https://blog.csdn.net/soslinken/article/details/50468896
在项目开发过程中,总会牵扯到接口文档的设计与编写,之前使用的都是office工具,写一个文档,总也是不够漂亮和直观。好在git上的开源大神提供了生成文档的工具,so来介绍一下!
该工具是Nodejs的模块,请务必在使用前安装好nodejs环境!
工具名称:apiDoc
Git地址:https://github.com/apidoc/apidoc
项目地址:http://apidocjs.com/
样例项目:http://apidocjs.com/example_basic/
apoDoc是从源码的注释中生成RestFul api 文档,样子还是蛮漂亮的……
一、apidoc简介
apidoc是一款可以有源代码中的注释直接自动生成api接口文档的工具,它几乎支持目前主流的所有风格的注释。例如:
Javadoc风格注释(可以在C#, Go, Dart, Java, JavaScript, PHP, TypeScript等语言中使用)
/*** This is a comment.*/
CoffeeScript
###
This is a comment.
###
Elixir
@apidoc """
This is a comment.
"""
Erlang (注释中的‘%’是可选的)
%{
% This is a comment.
%}
Perl (Doxygen)
#**
# This is a comment.
#*
Python
"""
This is a comment.
"""
Ruby
=begin
This is a comment.
=end
Lua
--[[
This is a comment.
--]]
二、apidoc使用
可以通过以下命令安装apidoc:
npm install apidoc -g
运行:
apidoc -i myapp/ -o apidoc/ -t mytemplate/
2.1 apidoc 命令参数列表:
参数 | 描述 |
---|---|
-h, --help | 查看帮助文档 |
-f --file-filters |
指定读取文件的文件名过滤正则表达式(可指定多个) 例如: apidoc -f ".*\\.js$" -f ".*\\.ts$" 意为只读取后缀名为js和ts的文件默认值: .clj .cls .coffee .cpp .cs .dart .erl .exs? .go .groovy .ino? .java .js .jsx .kt .litcoffee lua .p .php? .pl .pm .py .rb .scala .ts .vue
|
-e --exclude-filters |
指定不读取的文件名过滤正则表达式(可指定多个) 例如: apidoc -e ".*\\.js$" 意为不读取后缀名为js的文件默认: ''
|
-i, --input |
指定读取源文件的目录 例如: apidoc -i myapp/ 意为读取myapp/ 目录下面的源文件默认值: ./
|
-o, --output |
指定输出文档的目录 例如: apidoc -o doc/ 意为输出文档到doc 目录下默认值: ./doc/
|
-t, --template |
指定输出的模板文件 例如: apidoc -t mytemplate/ 默认: path.join(__dirname, '../template/')(使用默认模板)
|
-c, --config |
指定包含配置文件(apidoc.json)的目录 例如: apidoc -c config/ 默认: ./
|
-p, --private |
输出的文档中是否包含私有api 例如: apidoc -p true 默认: false
|
-v, --verbose |
是否输出详细的debug信息 例如: apidoc -v true 默认: false
|
2.2 配置(apidoc.json)
每次导出接口文档都必须要让apidoc读取到apidoc.json
文件(如果未添加配置文件,导出报错),你可以在你项目的根目录下添加apidoc.json
文件,这个文件主要包含一些项目的描述信息,比如标题、简短的描述、版本等,你也可以加入一些可选的配置项,比如页眉、页脚、模板等。
apidoc.json
{"name": "example","version": "0.1.0","description": "apiDoc basic example","title": "Custom apiDoc browser title","url" : "https://api.github.com/v1"
}
如果你的项目中使用了package.json
文件(例如:node.js工程),那么你可以将apidoc.json
文件中的所有配置信息放到package.json
文件中的apidoc参数中:
package.json
{"name": "example","version": "0.1.0","description": "apiDoc basic example","apidoc": {"title": "Custom apiDoc browser title","url" : "https://api.github.com/v1"}
}
apidoc.json配置项
参数 | 描述 |
---|---|
name |
工程名称 如果 apidoc.json 文件中没有配置该参数,apidoc 会尝试从pakcage.json 文件中读取
|
version |
版本 如果 apidoc.json 文件中没有配置该参数,apidoc 会尝试从pakcage.json 文件中读取
|
description |
工程描述 如果 apidoc.json 文件中没有配置该参数,apidoc 会尝试从pakcage.json 文件中读取
|
title | 浏览器标题 |
url |
api路径前缀 例如: https://api.github.com/v1
|
sampleUrl | 如果设置了该参数,那么在文档中便可以看到用于测试接口的一个表单(详情可以查看参数@apiSampleReques) |
header.title | 页眉导航标题 |
header.filename | 页眉文件名(markdown) |
footer.title | 页脚导航标题 |
footer.filename | 页脚文件名(markdown) |
order |
接口名称或接口组名称的排序列表 如果未定义,那么所有名称会自动排序 "order":[ "Error", "Define", "PostTitleAndError", "PostError" ] |
三、 apidoc注释参数
3.1 @api
【必填字段】否则,apidoc
会忽略该条注释
@api {method} path [title]
参数列表:
参数 | 必填 | 描述 |
---|---|---|
method | yes | 请求类型:DELETE, GET, POST, PUT, ...更多 |
path | yes | 请求路径 |
title | no | 接口标题 |
例:
/*** @api {get} /user/:id*/
3.2 @apiDefine
@apiDefine name [title][description]
定义注释模块(类似于代码中定义一个常量),对于一些通用可复用的注释模块(例如:接口错误响应模块),只需要在源代码中定义一次,便可以在其他注释模块中随便引用,最后在文档导出时会自动替换所引用的注释模块,定义之后您可以通过@apiUse
来引入所定义的注释模块。(注:可以同时使用@apiVersion
来定义注释模块的版本)
参数列表:
参数 | 必填 | 描述 |
---|---|---|
name | yes |
注释模块名称(唯一),不同@apiVersion 可以定义相同名称的注释模块
|
title | no | 注释模块标题 |
description | no | 注释模块详细描述(详细描述另起一行,可包含多行) |
例:
/*** @apiDefine MyError* @apiError UserNotFound The <code>id</code> of the User was not found.*//*** @api {get} /user/:id* @apiUse MyError*/
/*** @apiDefine admin User access only* This optional description belong to to the group admin.*//*** @api {get} /user/:id* @apiPermission admin*/
3.3 @apiDeprecated
@apiDeprecated [text]
标注一个接口已经被弃用
参数列表:
参数 | 必填 | 描述 |
---|---|---|
text | yes | 多行文字描述 |
例:
*** @apiDeprecated*//*** @apiDeprecated use now (#Group:Name).** Example: to set a link to the GetDetails method of your group User* write (#User:GetDetails)*/
3.4 @apiDescription
@apiDescription text
api接口的详细描述
参数列表:
参数 | 必填 | 描述 |
---|---|---|
text | yes | 多行文字描述 |
/*** @apiDescription This is the Description.* It is multiline capable.** Last line of Description.*/
3.5 @apiError
@apiError [(group)] [{type}] field [description]
错误返回参数
参数列表:
参数 | 必填 | 描述 |
---|---|---|
(group) | no |
所有的参数都会通过这个参数进行分组,如果未设置,默认值为Error 4xx
|
{type} | no |
返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]} )
|
field | yes | 返回id |
description | no | 参数描述 |
例:
/*** @api {get} /user/:id* @apiError UserNotFound The <code>id</code> of the User was not found.*/
3.6 @apiErrorExample
@apiErrorExample [{type}] [title]example
接口错误返回示例(格式化输出)
参数列表:
参数 | 必填 | 描述 |
---|---|---|
type | no | 响应类型 |
title | no | 示例标题 |
example | yes | 示例详情(兼容多行) |
例:
/*** @api {get} /user/:id* @apiErrorExample {json} Error-Response:* HTTP/1.1 404 Not Found* {* "error": "UserNotFound"* }*/
3.7 @apiExample
@apiExample [{type}] titleexample
接口方式请求示例
参数列表:
参数 | 必填 | 描述 |
---|---|---|
type | no | 请求内容格式 |
title | yes | 示例标题 |
example | yes | 示例详情(兼容多行) |
/*** @api {get} /user/:id* @apiExample {curl} Example usage:* curl -i http://localhost/user/4711*/
3.8 @apiGroup
@apiGroup name
定义接口所属的接口组,虽然接口定义里不需要这个参数,但是您应该在每个接口注释里都添加这个参数,因为导出的接口文档会以接口组的形式导航展示。
参数列表:
参数 | 必填 | 描述 |
---|---|---|
name | yes | 接口组名称(用于导航,不支持中文) |
例:
/*** @api {get} /user/:id* @apiGroup User*/
3.9 @apiHeader
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
描述接口请求头部需要的参数(功能类似@apiParam
)
参数列表:
参数 | 必填 | 描述 |
---|---|---|
(group) | no |
所有的参数都会以该参数值进行分组(默认Parameter )
|
{type} | no |
返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]} )
|
field | yes | 参数名称(定义该头部参数为必填) |
[field] | yes | 参数名称(定义该头部参数为可选) |
=defaultValue | no | 参数默认值 |
description | no | 参数描述 |
例:
/*** @api {get} /user/:id* @apiHeader {String} access-key Users unique access-key.*/
3.10 @apiHeaderExample
@apiHeaderExample [{type}] [title]example
请求头部参数示例
参数列表:
参数 | 必填 | 描述 |
---|---|---|
type | no | 请求内容格式 |
title | no | 请求示例标题 |
example | yes | 请求示例详情(兼容多行) |
例:
/*** @api {get} /user/:id* @apiHeaderExample {json} Header-Example:* {* "Accept-Encoding": "Accept-Encoding: gzip, deflate"* }*/
3.11 @apiIgnore
@apiIgnore [hint]
如果你需要使用该参数,请把它放到注释块的最前面。如果设置了该参数,那么该注释模块将不会被解析(当有些接口还未完成或未投入使用时,可以使用该字段)
参数列表:
参数 | 必填 | 描述 |
---|---|---|
hint | no | 描接口忽略原因描述 |
例:
/*** @apiIgnore Not finished Method* @api {get} /user/:id*/
3.12 @apiName
@apiName name
接口名称,每一个接口注释里都应该添加该字段,在导出的接口文档里会已该字段值作为导航子标题,如果两个接口的@apiVersion
和@apiName
一样,那么有一个接口的注释将会被覆盖(接口文档里不会展示)
参数列表:
参数 | 必填 | 描述 |
---|---|---|
name | yes | 接口名称(相同接口版本下所有接口名称应该是唯一的) |
例:
/*** @api {get} /user/:id* @apiName GetUser*/
3.13 @apiParam
@apiParam [(group)] [{type}] [field=defaultValue] [description]
接口请求体参数
参数列表:
参数 | 必填 | 描述 |
---|---|---|
(group) | no |
所有的参数都会以该参数值进行分组(默认Parameter )
|
{type} | no |
返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]} )
|
{type{size}} | no |
返回类型,同时定义参数的范围{string{..5}} 意为字符串长度不超过5{string{2..5}} 意为字符串长度介于25之间<br/>`{number{100-999}}`意为数值介于100999之间
|
{type=allowedValues} | no |
参数可选值{string="small"} 意为字符串仅允许值为"small"{string="small","huge"} 意为字符串允许值为"small"、"huge"{number=1,2,3,99} 意为数值允许值为1、2、3、99{string {..5}="small","huge" 意为字符串最大长度为5并且值允许为:"small"、"huge"
|
field | yes | 参数名称(定义该请求体参数为必填) |
[field] | yes | 参数名称(定义该请求体参数为可选) |
=defaultValue | no | 参数默认值 |
description | no | 参数描述 |
例:
/*** @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.*/
3.14 @apiParamExample
@apiParamExample [{type}] [title]example
请求体参数示例
参数列表:
参数 | 必填 | 描述 |
---|---|---|
type | no | 请求内容格式 |
title | no | 请求示例标题 |
example | yes | 请求示例详情(兼容多行) |
例:
/*** @api {get} /user/:id* @apiParamExample {json} Request-Example:* {* "id": 4711* }*/
3.15 @apiPermission
允许访问该接口的角色名称
@apiPermission name
参数列表:
参数 | 必填 | 描述 |
---|---|---|
name | yes | 允许访问的角色名称(唯一) |
例:
/*** @api {get} /user/:id* @apiPermission none*/
3.16 @apiPrivate
@apiPrivate
定义私有接口,对于定义为私有的接口,可以在生成接口文档的时候,通过在命令行中设置参数 --private false|true
来决定导出的文档中是否包含私有接口
例:
/*** @api {get} /user/:id* @apiPrivate*/
3.17 @apiSampleRequest
@apiSampleRequest url
设置了该参数后,导出的html接口文档中会包含模拟接口请求的form表单;如果在配置文件apidoc.json
中设置了参数sampleUrl
,那么导出的文档中每一个接口都会包含模拟接口请求的form表单,如果既设置了sampleUrl
参数,同时也不希望当前这个接口不包含模拟接口请求的form表单,可以使用@apiSampleRequest off
来关闭。
参数列表:
参数 | 必填 | 描述 |
---|---|---|
url | yes |
模拟接口请求的url@apiSampleRequest http://www.example.com 意为覆盖apidoc.json 中的sampleUrl 参数@apiSampleRequest off 意为关闭接口测试功能
|
例:
发送测试请求到:http://api.github.com/user/:id
Configuration parameter sampleUrl: "http://api.github.com"
/*** @api {get} /user/:id*/
发送测试请求到:http://test.github.com/some_path/user/:id
(覆盖apidoc.json
中的sampleUrl
参数)
Configuration parameter sampleUrl: "http://api.github.com"
/*** @api {get} /user/:id* @apiSampleRequest http://test.github.com/some_path/*/
关闭接口测试功能
Configuration parameter sampleUrl: "http://api.github.com"
/*** @api {get} /user/:id* @apiSampleRequest off*/
发送测试请求到http://api.github.com/some_path/user/:id
(由于没有设置apidoc.json
中的sampleUrl
参数,所以只有当前接口有模拟测试功能)
Configuration parameter sampleUrl is not set
/*** @api {get} /user/:id* @apiSampleRequest http://api.github.com/some_path/*/
3.18 @apiSuccess
@apiSuccess [(group)] [{type}] field [description]
接口成功返回参数
参数列表:
参数 | 必填 | 描述 |
---|---|---|
(group) | no |
所有的参数都会以该参数值进行分组,默认值:Success 200
|
{type} | no |
返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]} )
|
field | yes | 返回值(返回成功码) |
=defaultValue | no | 参数默认值 |
description | no | 参数描述 |
例:
/*** @api {get} /user/:id* @apiSuccess {String} firstname Firstname of the User.* @apiSuccess {String} lastname Lastname of the User.*/
包含(group)
:
/*** @api {get} /user/:id* @apiSuccess (200) {String} firstname Firstname of the User.* @apiSuccess (200) {String} lastname Lastname of the User.*/
返回参数中有对象:
/*** @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.*/
返回参数中有数组:
/*** @api {get} /users* @apiSuccess {Object[]} profiles List of user profiles.* @apiSuccess {Number} profiles.age Users age.* @apiSuccess {String} profiles.image Avatar-Image.*/
3.19 @apiSuccessExample
@apiSuccessExample [{type}] [title]example
返回成功示例
参数列表:
参数 | 必填 | 描述 |
---|---|---|
type | no | 返回内容格式 |
title | no | 返回示例标题 |
example | yes | 返回示例详情(兼容多行) |
例:
/*** @api {get} /user/:id* @apiSuccessExample {json} Success-Response:* HTTP/1.1 200 OK* {* "firstname": "John",* "lastname": "Doe"* }*/
3.20@apiUse
@apiUse name
引入注释模块,如果当前模块定义了@apiVersion
,那么版本相同或版本最近的注释模块会被引入
参数列表:
参数 | 必填 | 描述 |
---|---|---|
name | yes | 引入注释模块的名称 |
例:
/*** @apiDefine MySuccess* @apiSuccess {string} firstname The users firstname.* @apiSuccess {number} age The users age.*//*** @api {get} /user/:id* @apiUse MySuccess*/
3.21 @apiVersion
@apiVersion version
定义接口/注释模块版本
参数列表:
参数 | 必填 | 描述 |
---|---|---|
version | yes | 版本号(支持APR版本规则:major.minor.patch) |
例:
/*** @api {get} /user/:id* @apiVersion 1.6.2*/
注:文中如有任何错误,请各位批评指正!
链接:https://www.jianshu.com/p/9353d5cc1ef8
实践:
node安装:https://blog.csdn.net/mengzuchao/article/details/88761308
相关命令:
# 解压
tar Jxvf node-v6.9.4-linux-x64.tar.xz
# 移动到方便管理的目录
mv node-v6.9.4-linux-x64 /usr/local/nodejs
# 设置环境变量
vim /etc/profile
export PATH=$PATH:/usr/local/nodejs/bin#安装apidoc
npm install apidoc -g#配置文件:/home/wwwroot/apidoc/src/apidoc.json{"name": "example","version": "0.1.0","description": "apiDoc basic example","title": "Custom apiDoc browser title","url" : "https://api.github.com/v1"}#源文件:/home/wwwroot/apidoc/src/GameController.php IBaseController.php#生成文档
/usr/local/node/bin/apidoc -i /home/wwwroot/apidoc/src -o /home/wwwroot/apidoc/
效果:
linux 使用apidoc 生成Restful web Api文档相关推荐
- Node与apidoc的邂逅——NodeJS Restful 的API文档生成
作为后台根据需求文档开发完成接口后,交付给前台(angular vue等)做开发,不可能让前台每个接口调用都去查看你的后台代码一点点查找.前台开发若不懂你的代码呢?让他一个接口一个接口去问你怎么调用, ...
- Api文档生成工具与Api文档的传播(pdf)
点击查看apidoc生成文档demo 1 环境和工具 win10 apidoc:注释生成api文档 wkhtmltopdf:apidoc生成的是html,不适合传播,于是通过wkhtmltopdf将h ...
- Maven学习总结(43)——利用javadoc插件生成项目的API文档
在进行Java学习的时候,相信大家都看过在线或者下载的java api文档,可能是html格式或者chm格式的,其实这些参考文档也是很容易生成的,这里介绍一个maven的插件来实现项目代码文档的生成. ...
- CMDB建设补充:教你用django+drf 怎么去生成漂亮的API文档
废话不多说,先看效果图 安装插件 pip install drf_yasg 在settings.py的INSTALLED_APPS里添加drf_yasg 在urls.py里面添加下面代码 from r ...
- gin 生成api文档_gin-swagger 生成RESTful风格OpenAPI文档
- 使用apidoc文档神器,快速生成api文档
写完api接口,就需要编写api文档了,如果一个个手写的话就很麻烦,就得使用apidoc只需要通过写注释,就可以快速生成文档了. 安装 第一步先安装全局模块apidoc. npm install ap ...
- Spring Boot整合swagger2(生成有左右菜单式的api文档界面)
一.pom.xml内容: <!--=====依赖swagger2 zhongzk 2019.7.7 --> <dependency><groupId>io.spri ...
- apidoc使用教程-编写漂亮的api文档
apidoc使用教程 更多干货 React 入门实战(干货) 分布式实战(干货) spring cloud 实战(干货) mybatis 实战(干货) spring boot 实战(干货) 构建中小型 ...
- knife4j API文档生成使用流程及详解
目录 初始化流程 详细注解分析 @Api @ApiOperation @ApiModelProperty @ApiImplicitParam @ApiImplicitParams @ApiIgnore ...
- admin.php生成地址,FastAdmin命令行一键生成API文档
一键生成API文档 FastAdmin中的一键生成API文档可以在命令行或后台一键生成我们API接口的接口测试文档,可以直接在线模拟接口请求,查看参数示例和返回示例. 准备工作 请确保你的API模块下 ...
最新文章
- Unity3D图形性能优化
- LSTM股票价格预测
- 每天进步一点点《ML - 基于层次的聚类》
- php 调用图,php 缩略图类(附调用示例)
- 帆软填报联动 控件联动的几种方式
- 汽车维保反欺诈系统的设计和算法应用
- Oracle 11g RAC 安装数据库软件找不到节点的解决
- 等价类划分法设计测试用例
- 《我的眼睛--图灵识别》第九章:训练:制作识别字库
- Android技术开发 必备网站及使用工具
- 百度seo引流怎么做?一个免费分享知识的平台
- 电脑在桌面点击鼠标右键反应慢
- 用户运营的核心是消费者心理分析
- 计算机软件考试考几天,【软考考试时间是多久?软考时间有多长?】- 环球网校...
- 提高数据分析思维能力的三大方法
- Python批量爬取华语天王巨星周杰伦的音乐
- 沈航计算机考研上岸,22考研:上岸学姐亲身经历偷偷告诉你,一战成硕究竟到努力到什么程度?...
- java excel 插入新行_POI ,Java 操作 Excel 實現行的插入(insert row)
- MapReduce关系代数运算——差
- 陕西师范大学计算机学院课表,陕西师范大学数学与信息科学学院课程表(一).doc...
热门文章
- axios传参 后台接收为空
- 理解[].forEach.call()
- 关于浏览器存储问题理解
- 解决问题:Exception during message handling: Unacceptable CPU info: CPU doesn't have compatibility...
- 使用 Google Guava 美化你的 Java 代码
- Linux C多线程编程
- AOS V0.6 发布,JavaEE 应用基础平台
- linux---动静态库编译及使用
- 梦之翼网络LAMP技术博客正式成立!
- Postfix 邮件队列删除