自动生成 Restful API 文档工具--Api2doc的简单搭建

前言

基于开源项目api2doc二次开发，兼容第三方Restful框架zbus等。

作者terran4j github项目地址

一、极简体验

1. 引入pom依赖：

<!-- API文档生成 -->
<dependency>
    <groupId>com.junya</groupId>
    <artifactId>api2doc</artifactId>
    <version>1.0.2-SNAPSHOT</version>
</dependency>

2. 启动项目，浏览器输入http://localhost:8080/api2doc/home.html试试看吧

二、简单搭建

1. 引入pom依赖。

<!-- API文档生成 -->
<dependency>
    <groupId>com.junya</groupId>
    <artifactId>api2doc</artifactId>
    <version>1.0.2-SNAPSHOT</version>
</dependency>

2. 项目配置文件中定义api2doc配置，顺便指定下springboot的服务端口号。

server:
  port: 8081

# api2doc配置
api2doc:
  enabled: true
  title: 综保区 - 基础服务 - 接口文档V1.0
  icon: https://s2.ax1x.com/2019/11/05/MSogSJ.jpg
  rootPath: /basic
  author: zhangsan

• enabled：是否启用，默认true
• title：文档标题
• icon：文档图标，支持常见图床。
• rootPath：根URL，为了兼容zbus新加的属性，默认会在url上添加根目录。
• author：新加的属性，全局配置接口API作者。可以在方法上单个接口配置，如：@ApiComment(value = "根据业务Id获取业务，申报配置，发票清单信息", order = 50, author = "苏彪")。优先级：方法上 > 全局。

3. 启动类添加注解@EnableApi2Doc：

@EnableApi2Doc
@SpringBootApplication
public class CargoApplication {
    public static void main(String[] args) {
        SpringApplication.run(CargoApplication.class, args);
    }
}

4. 在项目发布层（原Controller层）加api2doc的注解，以便让其自动扫描，如：

释义：

@Api2Doc 用于对文档的生成进行控制。

@Api2Doc 修饰在类上，表示这个类会参与到文档生成过程中，Api2Doc 服务 会扫描 Spring 容器中所有的 Route类，只有类上有 @Api2Doc 的类， 才会被生成文档，一个类对应于文档页面左侧的一级菜单项，@Api2Doc 的 name 属性则表示这个菜单项的名称。

@Api2Doc 也可以修饰在方法，不过在方法上的 @Api2Doc 通常是可以省略。

@Api2Doc(ignore = true)用来过滤不想生成文档的方法：
现在同时在@ApiComment(ignore = true)中加了ignore属性，而且优先级大于@Api2Doc中的。

@Api2Doc(order = 6)用来排序，越小越靠前。
现在同时在@ApiComment(order= 1)中加了order属性，而且优先级大于@Api2Doc中的。

@Desc(description = "按分区获取货代往来客户")新加的注解，用来标注此方法的简介。

针对多个方法参数都包含某个字段，可以将注释加到实体类上，然后用seeClass，所有方法参数就不用加注释，插件自动获取到方法注释。如：

需要特别注意的是！！！SpringBoot2.2.2版下的freemarker源代码做了更新，以下请看：（为了简洁…只保留了属性部分，方法部分大家可以自行查看）

public class FreeMarkerProperties extends AbstractTemplateViewResolverProperties {
    public static final String DEFAULT_TEMPLATE_LOADER_PATH = "classpath:/templates/";
    public static final String DEFAULT_PREFIX = "";
    public static final String DEFAULT_SUFFIX = ".ftlh";
    private Map<String, String> settings = new HashMap();
    private String[] templateLoaderPath = new String[]{"classpath:/templates/"};
    private boolean preferFileSystemAccess = true;
  }

从以上属性值的初始化来看，suffix后缀改为了ftlh，意味着如果我们不指定，默认后缀就为ftlh！！！
因此，我们需要在yml文件加入如下配置，以防找不到页面报404:

spring:
	freemarker:
    	suffix: .ftl