你还在用Swagger?试试这个神器!
点击上方蓝色“方志朋”,选择“设为星标”
回复“666”获取独家整理的学习资料!
作者:Java旅途/ 周明尧(本文来自作者投稿)
今天给大家安利一款接口文档生成器——JApiDocs。
Swagger 想必大家都用过吧,非常方便,功能也十分强大。如果非要说Swagger 有什么缺点,想必就是注解写起来比较麻烦。如果我说有一款不用写注解,就可以生成文档的工具,你心动了吗?他就是我们今天的主角——JApiDocs。
下面我们一起来看看如何使用!
1. 添加依赖
<dependency><groupId>io.github.yedaxia</groupId><artifactId>japidocs</artifactId><version>1.3</version>
</dependency>
2. 配置生成参数
我们新建一个项目,然后随便写一个 main 方法,增加生成文档的配置,然后运行 main 方法。
DocsConfig config = new DocsConfig();
config.setProjectPath("F:\\Java旅途\\japi-docs"); // 项目根目录
config.setProjectName("japi-docs"); // 项目名称
config.setApiVersion("V1.0"); // 声明该API的版本
config.setDocsPath("F:\\test"); // 生成API 文档所在目录
config.setAutoGenerate(Boolean.TRUE); // 配置自动生成
Docs.buildHtmlDocs(config); // 执行生成文档
3. 编码规范
由于 JApiDocs 是通过解析 Java 源码来实现的,因此如果要想实现想要的文档,还是需要遵循一定的规范。
3.1 类注释、方法注释和属性注释
如果想生成类的注释,可以直接在类上加注释,也可以通过加 @Description 来生成。
/*** 用户接口类*/
@RequestMapping("/api/user")
@RestController
public class UserController {}/*** @author Java旅途* @Description 用户接口类* @Date 2020-06-15 21:46*/
@RequestMapping("/api/user")
@RestController
public class UserController {}
如果我们想生成方法的注释,只能直接加注释,不能通过加 @Description 来生成。
/*** 查询用户* @param age 年龄* @return R<User>
*/
@GetMapping("/list")
public R<User> list(@RequestParam int age){User user = new User("Java旅途", 18);return R.ok(user);
}
JApiDocs 可以自动生成实体类。关于实体类属性的注释有三种方式,生成的效果都是一样的,像下面这样:
/*** 用户名称*/
private String name;
/*** 用户年龄*/
private int age;
// 用户名称
private String name;
// 用户年龄
private int age;
private String name;// 用户名称
private int age;// 用户年龄
除了支持常用的 model 外,还支持 iOS 的 model 生成效果,像下面这样:
3.2 请求参数
如果提交的表单是 application/x-www-form-urlencoded 类型的key/value格式,则通过@param注解来获取参数,在参数后面添加注释,示例如下:
/*** @param age 年龄*/
@GetMapping("/list")
public R<User> list(@RequestParam int age){User user = new User("Java旅途", 18);return R.ok(user);
}
生成的文档效果如下:
请求参数
参数名 | 类型 | 必须 | 描述 |
---|---|---|---|
age | int | 否 | 年龄 |
如果提交的表单是 application/json 类型的 JSON 数据格式,像下面这样:
/*** @param user* @return*/
@PostMapping("/add")
public R<User> add(@RequestBody User user){return R.ok(user);
}
生成的文档效果如下:
请求参数
{"name": "string //用户名称","age": "int //用户年龄"
}
3.3 响应结果
我们知道,如果 Controller 声明了@RestController,SpringBoot 会把返回的对象直接序列成 JSON 数据格式返回给前端。JApiDocs 也利用了这一特性来解析接口返回的结果,但由于 JApiDocs 是静态解析源码的,因此你要明确指出返回对象的类型信息,JApiDocs 支持继承、泛型、循环嵌套等复杂的类解析。
因此我们不需要再写注释,它会根据我们的返回结果进行解析,效果如下:
返回结果:
{"code": "int","msg": "string","data": {"name": "string //用户名称","age": "int //用户年龄"}
}
最终生成的接口文档像下面这样:
4. 高级配置
4.1 @ApiDoc
如果你不希望把所有的接口都导出,可以在配置中设置config.setAutoGenerate(Boolean.FALSE); 然后在想要生成的接口上添加 @ApiDoc。
@ApiDoc 有以下三个属性:
result:可以直接声明返回的对象类型。如果你进行声明,将覆盖SpringBoot 的返回对象;
url:请求URL,扩展字段。用于支持非 SpringBoot 项目;
method:请求方法,扩展字段。用于支持非 SpringBoot 项目。
@ApiDoc(result = User.class, url = "/api/user/view", method = "post")
4.2 @Ignore
如果不想导出对象里面的某个字段,可以给这个字段加上 @Ignore 注解。这样 JApiDocs 导出文档的时候就会自动忽略掉了。
public class User {@Ignoreprivate int age;
}
5. 总结
JApiDocs 就介绍到这里了,优势劣势大家很容易就看出来了。几乎不需要注释即可生成接口文档,仅有的几个注释我们也可以通过 IDE 来自动生成。但是 JApiDocs 不具备 Swagger 在线调试功能。如果有一天 JApiDocs 支持在线调试后,那时候肯定会有一大波追随者,毕竟写代码的都不愿意写多余的注解。
热门内容:
一个 SpringBoot 项目该包含哪些?
卸载Notepad++!事实已证明,它更牛逼……
聊聊订单系统的设计?
讨论:Service层需要接口吗?
最近面试BAT,整理一份面试资料《Java面试BAT通关手册》,覆盖了Java核心技术、JVM、Java并发、SSM、微服务、数据库、数据结构等等。获取方式:点“在看”,关注公众号并回复 666 领取,更多内容陆续奉上。
明天见(。・ω・。)ノ♡
你还在用Swagger?试试这个神器!相关推荐
- 你还在用 Swagger?试试这个神器!
今天给大家安利一款接口文档生成器--JApiDocs. Swagger想必大家都用过吧,非常方便,功能也十分强大.如果非要说Swaager有什么缺点,想必就是注解写起来比较麻烦.如果我说有一款不用写注 ...
- swagger隐藏实体类字段_你还在用 Swagger?试试这个神器!
Java技术栈 www.javastack.cn 关注优质文章 今天给大家安利一款接口文档生成器--JApiDocs. swagger想必大家都用过吧,非常方便,功能也十分强大.如果要说swagger ...
- 还在用Swagger生成接口文档?我推荐你试试它.....
点击上方"方志朋",选择"设为星标" 回复"666"获取新整理的面试文章 JApiDocs是一个无需额外注解.开箱即用的SpringBoot ...
- 还在用Swagger?我推荐这款零代码侵入的接口管理神器!
静态的 Swagger 们跟不上频繁变更的代码 "为什么改了这个没告诉我","实际功能和文档上说的不一样啊".这些话大家做开发的想必耳朵都听出老茧了.真不是故意 ...
- 还在用Swagger?我推荐这款零代码侵入的接口管理神器
静态的 Swagger 们跟不上频繁变更的代码 "为什么改了这个没告诉我","实际功能和文档上说的不一样啊".这些话大家做开发的想必耳朵都听出老茧了.真不是故意 ...
- springboot 中文文档_还在用 Swagger生成接口文档?我推荐你试试它
JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具. 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又不得不做的事情,我们都不喜欢写文档,但除非项目前后 ...
- 还在用 Swagger(丝袜哥)生成接口文档?我推荐你试试它。。。
作者:小鱼儿511 https://blog.csdn.net/dongbeiou/article/details/106771453 JApiDocs是一个无需额外注解.开箱即用的SpringBoo ...
- jstree中文api文档_还在用 Swagger(丝袜哥)生成接口文档?我推荐你试试它。。。...
作者:小鱼儿511https://blog.csdn.net/dongbeiou/article/details/106771453JApiDocs是一个无需额外注解.开箱即用的SpringBoot接 ...
- radiobutton怎么变成竖排_衣服如此凌乱?怎么能忍受的了?衣柜收纳,试试这些神器吧...
每次从衣柜里找件衣服,可以说是各种姿势用尽,什么头颅伸进式.全身埋没式,半蹲翻找式,简直就是一场激烈的生活战争,无奈衣服找到后,你还需要收拾这惨不忍睹的战后现场-,为了解放你的双手,节省你的时间,不妨 ...
最新文章
- window.external.JavaScriptCallCpp
- rmi远程代码执行漏洞_【最新漏洞简讯】WebLogic远程代码执行漏洞 (CVE202014645)
- 辅助驾驶等级_双AMR电机位置传感器,助力自动驾驶安全出行
- mysql数据库开发笔记_MySQL数据库生成数据库说明文档
- Jmeter通过CSV Data Set Config参数化
- vue写的页面title中ico图标不显示的问题
- pl/sql developer安装与配置
- ORACLE完整数据库实例迁移
- JavaScript — json文件的读取与写入
- css3中的@font-face你真的了解吗
- 发烧游戏机型的计算机制配单,万元主机配置发烧级游戏设计渲染配置单
- 计算机的五个发展阶段详细介绍,计算机的发展阶段可以分为那五个阶段吗?
- Android保存图片到系统图库并通知系统相册刷新
- 办公:office办公软件Excel表格的打印技巧
- 华为智能音响2代鸿蒙,99999元!华为全屋智能方案来了:鸿蒙生态是亮点
- Java8 提供CompletableFuture来简化高并发异步处理编程
- 大商创是用哪种php柜架写的,大商创商家入驻入口去除说明简述
- 深度学习模型训练和关键参数调优详解
- “汉语”迟早要淘汰“英语”(精品转贴)
- 胡策day 10.26 T2 人、镜子与墙
热门文章
- Cmake软件编译opencv报错,CMake Warning at cmake/OpenCVDownload.cmake:193 (message): FFMPEG: Download...
- 集合、泛型、增强for
- 设计模式的征途—10.装饰(Decorator)模式
- RobotFramework下的http接口自动化Set Request Body 关键字的使用
- Atitit 为什么网络会有延时 电路交换与分组交换的区别
- 读大叔深入理解javascript(2)
- TCP拥塞控制算法内核实现剖析(二)
- 各大IT公司笔试真题汇总开发人员一定要加入收藏夹的网站(收藏)
- 刻意练习:LeetCode实战 -- 二叉树的后序遍历
- Matlab与数据结构 -- 求向量或矩阵的最大值