共计 1668 个字符,预计需要花费 5 分钟才能阅读完成。
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/JA…
- 中文文档:https://japidocs.agilestudio….