干掉 Swagger (丝袜哥)，试试这个新工具！

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

编写和维护 API 文档这个事情，对于后端程序员来说，是一件恼人但又不得不做的事情，我们都不喜欢写文档，但除非项目前后端代码都是自己写的，否则 API 文档将是前后端协作中一个不可或缺的沟通界面。既然不可避免，那就想办法弄个轮子吧。人生苦短，必须偷懒。

无图无真相，生成文档的效果如下：

![](https://image-1300566513.cos.ap-guangzhou.myqcloud.com/upload/images/20210323/a54a1aeea4464eeb9e8445328829ef22.png)

相比 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 的帮助下，这个工作将是轻松愉悦的：

![](https://image-1300566513.cos.ap-guangzhou.myqcloud.com/upload/images/20210323/eb3e81b1b0ac42b5a359672703d8b8ca.png)

然后你在任意一个 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/

干掉 Swagger (丝袜哥)，试试这个新工具！

全部评论: 0 条

最新发布

最新评论