Web API 文档生成工具 apidoc
原文地址:梁桂钊的博客
在服务端开发过程中,我们需要提供一份 API 接口文档给 Web 端和移动端使用。实现 API 接口文档编写工作,有很多种方式,例如通过 Word 文档编写,或者通过 MediaWiki 进行维护。此外,还有比较流行的方式是利用 Swagger 自动化生成文档。这里,笔者想分享另一个 Web API 文档生成工具 apidoc。
apidoc 是通过源码中的注释来生成 Web API 文档。因此,apidoc 对现有代码可以做到无侵入性。此外,apidoc 可以支持多种语言 C#, Go, Dart, Java, JavaScript, PHP, TypeScript (all DocStyle capable languages),CoffeeScript,Erlang,Perl,Python,Ruby,Lua。通过 apidoc 可以非常方便地生成可交互地文档页面。
开始入门
首先,我们需要 node.js 的支持。在搭建好 node.js 环境后,通过终端输入 npm 命名进行安装。
npm install apidoc -g
复制代码
接着,我们还需要添加 apidoc.json 文件到项目工程的根目录下。
{"name": "example","version": "0.1.0","description": "apiDoc basic example","title": "Custom apiDoc browser title","url" : "https://api.github.com/v1"
}
复制代码
这里,笔者主要演示 Java 注释如何和 apidoc 结合使用。现在,我们先来看一个案例。
/*** @api {GET} logistics/policys 查询签收预警策略* @apiDescription 查询签收预警策略* @apiGroup QUERY* @apiName logistics/policys* @apiParam {Integer} edition 平台类型* @apiParam {String} tenantCode 商家名称* @apiPermission LOGISTICS_POCILY*/
复制代码
最后,我们在终端输入 apidoc 命令进行文档生成。这里,我们用自己的项目工程的根目录替代 myapp/,用需要生成文档的地址替代 apidoc/。
apidoc -i myapp/ -o apidoc/
复制代码
例如,笔者的配置是这样的。
apidoc -i /Users/lianggzone/Documents/dev-space/git-repo -o /Users/lianggzone/Documents/dev-space/apidoc/
复制代码
代码注释
@api
@api 标签是必填的,只有使用 @api 标签的注释块才会被解析生成文档内容。格式如下:
@api {method} path [title]
复制代码
这里,有必要对参数内容进行讲解。
参数名 | 描述 |
---|---|
method | 请求方法, 如 POST,GET,POST,PUT,DELETE 等。 |
path | 请求路径。 |
title【选填】 | 简单的描述 |
@apiDescription
@apiDescription 对 API 接口进行描述。格式如下:
@apiDescription text
复制代码
@apiGroup
@apiGroup 表示分组名称,它会被解析成一级导航栏菜单。格式如下:
@apiGroup name
复制代码
@apiName
@apiName 表示接口名称。注意的是,在同一个 @apiGroup 下,名称相同的 @api 通过 @apiVersion 区分,否者后面 @api 会覆盖前面定义的 @api。格式如下:
@apiName name
复制代码
@apiVersion
@apiVersion 表示接口的版本,和 @apiName 一起使用。格式如下:
@apiVersion version
复制代码
@apiParam
@apiParam 定义 API 接口需要的请求参数。格式如下:
@apiParam [(group)] [{type}] [field=defaultValue] [description]
复制代码
这里,有必要对参数内容进行讲解。
参数名 | 描述 |
---|---|
(group)【选填】 | 参数进行分组 |
{type}【选填】 | 参数类型,包括{Boolean}, {Number}, {String}, {Object}, {String[]}, (array of strings), ... |
{type{size}}【选填】 | 可以声明参数范围,例如{string{..5}}, {string{2..5}}, {number{100-999}} |
{type=allowedValues}【选填】 | 可以声明参数允许的枚举值,例如{string="small","huge"}, {number=1,2,3,99} |
field | 参数名称 |
[field] | 声明该参数可选 |
=defaultValue【选填】 | 声明该参数默认值 |
description【选填】 | 声明该参数描述 |
类似的用法,还有 @apiHeader 定义 API 接口需要的请求头,@apiSuccess 定义 API 接口需要的响应成功,@apiError 定义了 API 接口需要的响应错误。
这里,我们看一个案例。
/*** @apiParam {Integer} edition=1 平台类型* @apiParam {String} [tenantCode] 商家名称*/
复制代码
此外,还有 @apiParamExample,@apiHeaderExample, @apiErrorExample,@apiSuccessExample 可以用来在文档中提供相关示例。
@apiPermission
@apiPermission 定义 API 接口需要的权限点。格式如下:
@apiPermission name
复制代码
此外,还有一些特别的注解。例如 @apiDeprecated 表示这个 API 接口已经废弃,@apiIgnore 表示忽略这个接口的解析。关于更多的使用细节,可以阅读官方文档:http://apidocjs.com/#demo
完整的案例
最后,我们用官方的案例,讲解下一个完整的配置。
首先,配置 apidoc.json,内容如下:
{"name": "example","version": "0.1.0","description": "A basic apiDoc 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"* }*/
复制代码
然后,执行命名生成文档。
apidoc -i myapp/ -o apidoc/
复制代码
生成的页面,如下所示。
(完)
更多精彩文章,尽在「服务端思维」微信公众号!
Web API 文档生成工具 apidoc相关推荐
- apiDoc 一款很不错api文档生成工具
apiDoc 一款很不错api文档生成工具,在开发接口的时候,需要给同事看相应的接口文档.给大家推荐一个生成文档的工具--apiDoc,最后生成的文档以网页的形式发布,方便快捷,便于阅读. 创建项目目 ...
- 猿创征文|小而巧的API文档生成工具之smart-doc
文章目录 smart-doc介绍 smart-doc特性 smart-doc的最佳搭档 谁在使用smart-doc smart-doc的优缺点 smart-doc和swagger区别比较 smart- ...
- java smart算法_Java Restful API 文档生成工具 smart-doc
谁说生成api文档就必须要定义注解? 谁说生成接口请求和返回示例必须要在线? 用代码去探路,不断尝试更多文档交付的可能性. 如果代码有生命,为什么不换种方式和它对话! 一.背景 没有背景.就自己做自己 ...
- Api文档生成工具与Api文档的传播(pdf)
点击查看apidoc生成文档demo 1 环境和工具 win10 apidoc:注释生成api文档 wkhtmltopdf:apidoc生成的是html,不适合传播,于是通过wkhtmltopdf将h ...
- php自写api文档生成工具
框架改版后的第二个版本定下来了,这两天也比较轻松,于是就折腾给项目建个好看的api文档. 各种折腾.先是折腾phpDocumentor2,用phpdoc开源工具来建立文档,好不容易安装成功,各个模板都 ...
- springboot的api_【粉丝投稿】无需额外注解的 SpringBoot API文档生成工具
点击上方"蓝字"关注我们吧! JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具. 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又 ...
- android api文档_【粉丝投稿】无需额外注解的 SpringBoot API文档生成工具
点击上方"蓝字"关注我们吧! JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具. 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又 ...
- [aspnetcore.apidoc]一款很不错的api文档生成工具
简单徐速一下为什么选用了aspnetcore.apidoc 而没有选用swagger 最初我们也有在试用swagger,但总是有些感觉,感觉有点不满意,就但从api文档角度来说,从前后端文档沟通角度来 ...
- 一款零注解侵入的 API 文档生成工具,你用过吗?
以下文章来源方志朋的博客,回复"666"获面试宝典 介绍 smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具,smart ...
- 关于深度学习框架Hamaa与Python API文档生成工具Sophon
五月两场 | NVIDIA DLI 深度学习入门课程 5月19日/5月26日一天密集式学习 快速带你入门阅读全文> 正文共1988个字,预计阅读时间12分钟. 前言 最近三个月我主要花时间在造 ...
最新文章
- JS开发中常用的小技巧
- 全球及中国皮裤行业消费需求及未来产销前景预测报告2022-2027年
- 使用SAP WebIDE创建开发Java应用,并且在浏览器里调试
- echarty轴自定义显示不全_表格打印不全怎么办?这招超简单!
- Create React App 2.0 华丽登场
- es6 新增数据类型_ES6新增特性整理
- python骗局-说真的!大家做Python一定不要只会一个方向
- Linux下常用网络配置命令
- 航空三字代码表_航空公司三字代码表
- [C语言]切比雪夫多项式,并写入到文件中
- 《雍正皇帝》文化专有词翻译策略的研究现状(纽马克)
- win10重装win7后usb键盘鼠标都失灵
- 通过python各种开源库,开发一个适合大部分公司测试项目框架,确定名字AutoTestProjects
- 高德定位SDK踩坑-高精度模式下获取不到GPS定位(无网络环境)
- 图灵奖得主长文报告:是什么开启了计算机架构的新黄金十年?
- 哈里斯鹰优化算法(HHO)附matlab code链接
- Linux中网络连接不上解决方案大全
- QT (C++)安装5.14
- web页面如何进行电话拨打
- vega8显卡和mx250哪个好_Ryzen 7 4800U 现身 3DMark 11 数据库,Vega 8 核显也能超越 MX 250...
热门文章
- python中functools_Python中functools模块的常用函数解析
- json字符串和字典的区别
- 你确认退出吗 html,按退出会 执行2次弹出确认窗口,为何?
- 例4.2 又一版A+B - 九度教程第43题(进制转换)
- java simpedateformat_java中Date,SimpleDateFormat
- python颜色参数_python matplotlib:plt.scatter() 大小和颜色参数详解
- python中的is和==
- 基于jsonwebtoken(JWT) 的web认证 (Node版实现)
- YUV420及YUV422格式的采集存储方式
- php正则表达式修饰符详解