无需额外注解的 SpringBoot API文档生成工具

前言

大家好,我叫叶大侠,一名独立开发者。这个文档工具是我17年的一个想法,当时还是在公司里面上班,负责App客户端的开发工作,当时后端童鞋写文档的意愿比较低,总是要等他们开发完接口,然后才在微信上沟通接口细节,显然这样的效率很低,导致前端的童鞋总是差不多deadline的时候才猛加班。

后面我建议让他们能不能先把接口设计好,这样大家可以并行开发,但显然会增加了他们不少工作量,于是不太乐意。在这样的背景下,我就想能不能搞个工具来自动生成这个文档,并且尽可能不增加他们的工作量。

当时组里面后端用的还是play框架,我调研了一下这个框架,结合java强类型的语言特性,有了基本的思路,于是私下花了差不多两周的时间做了个很初级的版本,虽然简陋,但基本可以满足对文档的需求了。

这就是JApiDocs最初的想法来源。

后来觉得这个东西别人也许也会需要,后面我就把它整理出来开源了,并扩展支持了SpringBoot、JFinal框架。

不久这个项目受到了开源中国的推荐,收获了一波星星,后面还受邀到源创会去分享了一下,这算是这个项目的巅峰时刻了。

后来由于我出来创业,慢慢就没时间打理这个项目了,关注度也慢慢下去了。

内心始终有股遗憾,码农生涯如果没有个像样的开源产品,感觉不是很圆满,所以我又回来继续完善这个开源工具了,虽然不知道最终是否会得到大家认可,但还是想去尝试一下。

简介

编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又不得不做的事情,我们都不喜欢写文档,但除非项目前后端代码都是自己写的,否则API文档将是前后端协作中一个不可或缺的沟通界面。

JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具。

无图无真相,生成文档的效果如下:

image

相比Swagger要写一堆注解,Spring Rest Docs需要写测试用例,才能生成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的帮助下,这个工作将是轻松愉悦的:

image

然后你在任意一个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分钟不到就能认识一个提高工作效率的工具,让你把更多的时间花在更加有价值的事情上,你确认不看一下吗?

仓库地址 | 中文文档

温馨提示:GitHub上收藏和支持一个项目最好的方式就是点个star哦!

image

接下来的计划

这个工具的目标很明确,就是尽可能提升前后端沟通和开发效率。接下来的计划包括但不限于:

  1. 支持更多导出文档格式;
  2. 自动生成前端的接口代码,供App或网页前端开发同学直接使用;
  3. 把发生变化的接口标识出来;
  4. 对接一些开源mock平台等。

如果你有更好的想法,欢迎给我留言哦。