springboot 自动文档生成工具JApi集成

实例

官方文档

https://japidocs.agilestudio.cn/#/

源码

https://github.com/YeDaxia/JApiDocs

为什么选择JApi(优点)

1. 完全开源，有需求的可以二次开发，并且开发难度不高，这意味着你可以花比较少量的时间为自己的项目进行量身定制。
2. 由于其基于java doc注释的特性，基本上做到了无代码侵入，不会像swagger一样，为了展示文档写很多swagger配置和注解。
3. apidoc 界面美观，文档看着舒服。
4. 支持html，导出支持markdown和 pdf、word等，无论是自己看还是给客户、前端对接人员看都很方便。
5. 依赖少并且不想appiza 或者yapi那样需要独立部署。

缺点

1. 生成的apidoc资源是静态的，不能直接用springboot进行访问，需要进行一定的改造，这点不如swagger
2. 返回类型如果是数组（List,Map）时，不能很好的兼容，有的时候会报错或者无法显示返回内容。
3. 如果你的项目使用了advice进行了返回结果统一包装，那么可能无法展示包装的那一层结构。
4. 高度依赖controler和实体类必须有完整的注释，否则会很难看（不过如果连代码javadoc注释都不写，建议改行，程序员显然不适合你）

以上缺点如果能够接收或者能通过开发能力去解决，那么可以继续往下看。

如何开始

在父级module或者底层公共module中添加依赖：

        <dependency>
            <groupId>io.github.yedaxiagroupId>
            <artifactId>japidocsartifactId>
            <version>1.4.3version>
        dependency>

在controller或者distribution层增加配置生成类：

/**
 * japi文档生成初始化配置
 *
 * @author tino
 * @date 2020/8/31
 */
public class JApiDocsInitialization {
     

    /**
     * JApi run test
     *
     * @param args
     */
    public static void main(String[] args) {
     
        initialize();
    }

    /**
     * 自动生成api文档
     */
    public static void initialize() {
     
        DocsConfig config = new DocsConfig();
        String projectPath = System.getProperty("user.dir");
        config.setProjectPath(projectPath); // 项目根目录
        config.setProjectName("sa-dmc-api-doc"); // 项目名称
        config.setApiVersion("");       // 声明该API的版本
        // config.setDocsPath(projectPath + "/distribution/workshop-server/src/main/resources/static/apidoc"); // 生成API 文档所在目录
		config.setDocsPath(ClassUtils.getDefaultClassLoader().getResource("static/apidoc").getPath()); // 生成API 文档所在目录
        config.setAutoGenerate(Boolean.TRUE);  // 配置自动生成
        Docs.buildHtmlDocs(config); // 执行生成文档
    }
}

在resource下增加static/apidoc目录，执行代码，生成的文档就在此处，浏览器打开 static/apidoc/index.html查看文档效果，新建apidoc目录时为了区别于其他静态资源，还为了方便添加拦截器白名单。

如果需要使用域名+端口访问静态资源，还需要如下操作:

1.在 application.yml中增加：

spring:
  resources:
    static-locations: classpath:/static/

2.如果有登录拦截器又不需要登录访问文档，那么需要在拦截器白名单中增加"/apidoc/*""白名单。
3.（非必须）这个时候通过
http://localhost:端口/apidoc/index.html
还是不能访问文档起始页（404或者被登录拦截），那么可能是你的项目在配置中存在

@EnableWebMvc

通常使用了统一返回处理advice的会开启此配置，这个时候你需要在WebMvcConfigurer的实现中覆写addResourceHandlers方法使静态资源能够被访问。

/**
 * 登录拦截
 *
 * @author tino
 * @date 2020/4/13
 */
@Configuration
@EnableWebMvc
public class InterceptorConfig extends WebConfiguration implements WebMvcConfigurer {
     

    /**
     * 由于@EnableWebMvc注解导致的，原因大致是 @EnableWebMvc 引入了 WebMvcConfigurationSupport，spring就跳过springboot的 WebMvcAutoConfiguration，
     * 使得springboot没有扫描到 src/main/resources/static这些静态资源
     * 所以这里重写 重写addResourceHandlers方法，添加静态资源路径
     *
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
     
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/", "classpath:/templates/");
        super.addResourceHandlers(registry);
    }
}

如果想在启动时生成api文档，需要在启动类中增加：

    public static void main(String[] args) {
     
        SpringApplication.run(this.getClass(), args);
        // 启动时重新生成api文档
        JApiDocsInitialization.initialize();
    }

启动项目，访问 http://localhost:端口/apidoc/index.html ，api文档就在眼前。

可能遇到的问题

1.生成时进行到某个controller的时候后报空指针异常，原因是japi无法映射集合类型的聚合返回对象，你需要对接口的返回类型进行规范，最好是明确的对象，如果不想使用对象，那么需要你通过@ApiDoc自定义api文档，这样就不会报错：

    /**
     * 获取聚合数据
     *
     * @param startDate
     * @param endDate
     * @return
     */
    @ApiDoc(result = ArrayList.class, url = "getCount", method = "get")
    @GetMapping("/getCount")
    public List<Map<String, Object>> getCount(@RequestParam String startDate, @RequestParam String endDate) {
     
        return cardStatisticsService.getCount(startDate, endDate);
    }

2.发布到服务器上时无法访问静态资源——两种解决方式，1）本地生成文档到static/apidoc下，推到git远端，发布时打包即可；2）调整生成文档的生成路径为线上服务映射的跟域名下。