还在用Swagger(丝袜哥)生成接口文档?我推荐你试试它...
作者:叶大侠
JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具。
编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又不得不做的事情,我们都不喜欢写文档,但除非项目前后端代码都是自己写的,否则API文档将是前后端协作中一个不可或缺的沟通界面。既然不可避免,那就想办法弄个轮子吧。人生苦短,必须偷懒。
无图无真相,生成文档的效果如下:
相比Swagger要写一堆注解,Spring RestDocs需要写测试用例,才能生成API文档。JApiDocs 具有无痛集成的特点,你只需花几分钟就能知道它怎么用了。
快速开始
要使得JApiDcos正确工作,你写的代码应该是像下面的样子的:
/**
* 用户接口
*/
@RequestMapping("/api/user/")
@RestController
public class UserController {
/**
* 用户列表
* @param listForm
*/
@RequestMapping(path = "list", method = {RequestMethod.GET, RequestMethod.POST} )
public ApiResult<PageResult<UserVO>> list(UserListForm listForm){
return null;
}
/**
* 保存用户
* @param userForm
*/
@PostMapping(path = "save")
public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){
return null;
}
}
我们给Controller类和方法加上必要的注释,给接口方法返回相关的对象类型。是的,这样JApiDocs就能解析到相关的接口信息了,就跟我们平时写的代码是差不多的,但要注意,你要通过@param
来告诉JApiDocs接口的参数,但在IDE的帮助下,这个工作将是轻松愉悦的:
然后你在任意一个main入口方法执行下面的代码就可以生成文档了:
DocsConfig config = new DocsConfig();
config.setProjectPath("your springboot project path"); // 项目根目录
config.setProjectName("ProjectName"); // 项目名称
config.setApiVersion("V1.0"); // 声明该API的版本
config.setDocsPath("your api docs path"); // 生成API 文档所在目录
config.setAutoGenerate(Boolean.TRUE); // 配置自动生成
Docs.buildHtmlDocs(config); // 执行生成文档
接下来你只管好好写代码,生成Api文档的工作就可以交给JApiDocs了,你不需要再为额外编写和维护文档而烦恼。
功能特性
1、代码即文档
JApiDocs是通过直接解析SpringBoot的源码语法来工作的,所以只要Controller的语法符合一定的代码规范,有合理的注释,就可以直接导出文档。
2、支持导出HTML
便捷的导航和接口查看界面;可本地预览,或者部署到HTTP服务器。推荐部署到服务器,方便前后端展开协作。
3、同步导出客户端Model代码
支持导出Android端的 Java 和iOS端的 Object C Model代码,减少前端程序员的重复编码工作。
4、更多特性
支持接口搜索;支持不同版本和英文文档;自定义扩展等。
简洁的文档
再好用的东西,如果没有文档说明,别人也无从入手。为了让大家尽快上手,JApiDocs准备了一份极简的文档说明,确保你在几分钟就能用上JApiDocs。花5分钟不到就能认识一个提高工作效率的工具,让你把更多的时间花在更加有价值的事情上,你确认不看一下吗?
仓库地址:https://github.com/YeDaxia/JApiDocs 中文文档:https://japidocs.agilestudio.cn/#/zh-cn/
- KVM 虚拟化技术
- Gnuboard 漏洞分析
- HTTPS 原理与证书实践
- 企业防火墙之iptables
- MongoDB的备份与恢复
- 浅析XSS的几种测试方法
- MongoDB 分片集群技术
- hadoop任务测试
- Android查缺补漏(线程篇)-- AsyncTask的使用及原理详细分析
- Android查缺补漏(IPC篇)-- 进程间通讯基础知识热身
- Android查缺补漏(IPC篇)-- 进程间通讯之AIDL详解
- Android查缺补漏(IPC篇)-- 进程间通讯之Socket简介及示例
- Android查缺补漏(IPC篇)-- Bundle、文件共享、ContentProvider、Messenger四种进程间通讯介绍
- Android查缺补漏(View篇)--布局文件中的“@+id”和“@id”有什么区别?
- JavaScript 教程
- JavaScript 编辑工具
- JavaScript 与HTML
- JavaScript 与Java
- JavaScript 数据结构
- JavaScript 基本数据类型
- JavaScript 特殊数据类型
- JavaScript 运算符
- JavaScript typeof 运算符
- JavaScript 表达式
- JavaScript 类型转换
- JavaScript 基本语法
- JavaScript 注释
- Javascript 基本处理流程
- Javascript 选择结构
- Javascript if 语句
- Javascript if 语句的嵌套
- Javascript switch 语句
- Javascript 循环结构
- Javascript 循环结构实例
- Javascript 跳转语句
- Javascript 控制语句总结
- Javascript 函数介绍
- Javascript 函数的定义
- Javascript 函数调用
- Javascript 几种特殊的函数
- JavaScript 内置函数简介
- Javascript eval() 函数
- Javascript isFinite() 函数
- Javascript isNaN() 函数
- parseInt() 与 parseFloat()
- escape() 与 unescape()
- Javascript 字符串介绍
- Javascript length属性
- javascript 字符串函数
- Javascript 日期对象简介
- Javascript 日期对象用途
- Date 对象属性和方法
- Javascript 数组是什么
- Javascript 创建数组
- Javascript 数组赋值与取值
- Javascript 数组属性和方法
- 使用Keras构建具有自定义结构和层次图卷积神经网络(GCNN)
- 给大忙人写的单例模式的八种实现方法
- 在Python中使用Torchmoji将文本转换为表情符号
- 我通过三个故事终于学明白了三种工厂模式
- 《设计模式》系列-SOLID设计原则
- (力扣)面试题56 - I. 数组中数字出现的次数
- 玩转 Java8 中的 Stream 之从零认识 Stream
- 聊聊dubbo-go的DubboInvoker
- 剑指Offer 面试题03. 数组中重复的数字
- SDAccel矩阵乘法优化(一)
- 花式玩 Spring Security ,这样的用户定义方式你可能没见过!
- 一文胜千言的DHCP的讲解以及DHCP服务器的配置
- 小知识 词云制作
- 解决 Error starting userland proxy: listen tcp 0.0.0.0:6379: bind: address already in use
- Qt官方示例-菜单栏