nodejs下的apidoc 帮助接口文档生成
2024-05-13 14:04:54
在项目开发过程中，总会牵扯到接口文档的设计与编写，之前使用的都是office工具，写一个文档，总也是不够漂亮和直观。好在git上的开源大神提供了生成文档的工具，so来介绍一下！
该工具是Nodejs的模块，请务必在使用前安装好nodejs环境！
工具名称：apiDoc
Git地址：https://github.com/apidoc/apidoc
项目地址：http://apidocjs.com/
样例项目：http://apidocjs.com/example_basic/
apoDoc是从源码的注释中生成RestFul api 文档，样子还是蛮漂亮的……
自己写了的ApiDoc文档自动生成工具，避免每次写完后手动执行生成代码http://blog.csdn.net/soslinken/article/details/50476384
支持的注释样式:
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",
"url" : "https://api.github.com/v1"}
- 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",
"url" : "https://api.github.com/v1"
}
}
- 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
使用该注释的才能被识别成为文档的一块内容
method：请求方法，参见https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methodspath：请求路径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:
* curl -i http://localhost/user/4711
*/
- 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
* @apiSampleRequesthttp://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
* @apiSampleRequesthttp://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": "slocn@gamil.com",
* "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":"修改成功"}
*/
nodejs下的apidoc 帮助接口文档生成相关推荐
- spring-boot 一款无侵入型，轻量级的接口文档生成工具apiggs
spring-boot 一款无侵入型,轻量级的接口文档生成工具apiggs 名字叫:apiggs 使用只需两步,先把插件代码引入pom文件,然后编译打包即可 之后项目的target目录下,就会多出一个 ...
- 基于文档注释接口文档生成工具(代码0侵入附源码)
本文主要分享一个基于个人兴趣,旨在提高工作效率,开发了一个基于文档注释,接口文档生成工具,欢迎大佬指点. 源码以及使用demo地址 :传送门 1.前置介绍 1.1前世 现在大多数项目都走向了前后端分离 ...
- 放弃丑陋的 swagger-ui，使用 knife 接口文档生成神器
文章目录 接口生成利器 knife 介绍 springboot 整合 knife pom.xml 文件增加依赖 编写Swagger2Config配置文件 注意事项 总结 knife Gitee 地址: ...
- 扔掉Swagger，试试这款功能强大，零注解侵入的API接口文档生成工具！
欢迎关注方志朋的博客,回复"666"获面试宝典 介绍 smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具,smart-d ...
- 支持Dubbo接口文档生成的工具！
点击上方蓝色"程序猿DD",选择"设为星标" 回复"资源"获取独家整理的学习资料! 作者 | 肥朝 来源 | https://mp.weix ...
- java接口文档生成工具_接口文档生成
一.为什么要写接口文档? 1.正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员写的.一个工整的文档显得是非重要. 2.项目开发过程中前后端工程师有一个统一的文件进行沟通 ...
- Swagger自动接口文档生成框架————springboot整合swagger总结
swagger简介: swagger是一款开源的api接口文档生成工具. Swagger的项目主页:https://swagger.io/ 目前比较流行的做法是在代码中加入swagger相关的注 ...
- java接口文档生成工具_【分享】接口文档生成工具apipost
一.为什么要写接口文档? 正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员写的.一个工整的文档显得是非重要. 项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发 ...
- 一款零注解API接口文档生成工具
smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具,基于接口源码来分析生成接口文档,不采用任何注解侵入到业务代码中.只需要按照java-do ...
最新文章
- 【题解】Luogu P2347 砝码称重
- 3.1HTML5样式的使用
- 硬件基础 —— 电阻
- UCall能真正的免费打电话,爽
- Maven-dependencyManagement与import
- （转）财新特稿丨风口浪尖上，李笑来谈ICO
- MLOps- 吴恩达Andrew Ng Data Definition and Baseline Week3 实验作业
- 关于本学期学校数据库课程的总结和一些心得
- iOS如何通过安装描述文件获取设备UDID
- fatal: unable to access ‘https://github.com/thm123/algos.git/‘: Received HTTP code 400 from proxy af
- 数学之美 读书心得与笔记
- 80C51单片机PROTUES仿真C语言数码管点亮
- elasticsearch 修改已存在的filed值 和 新增filed
- 使用husky + lint-staged助力团队编码规范
- java hbase连接kerberos的几个常见错误
- Esxi6.7安装TinyCoreLinux
- 【HTM】层级实时记忆脑皮质学习算法 一、当前进度
- 教你急速快速批量插入1000万条数据到mysql数据库表面试题
- 反驳生命的起点是rna_生命起源学说或将被改写？“天外来客”陨石给科学家带来新发现！...
- linux怎么运行dat文件,dat文件扩展名，dat文件怎么打开？