Java API自动生成文档

Java API 文档自动生成有 swagger2 和 spring restdocs 两种受欢迎的工具。

Swagger2 的使用

介绍

swagger2通过配置，会提供了一个 url：http://localhost:8080/v2/api-docs，返回了所有 api 的信息。读取这个 url，将结果存储到swagger.json。利用 swagger2markup-maven-plugin 插件读取 swagger.json，生成一系列adoc文件。最后利用 asciidoctor-maven-plugin 插件将 index.adoc 文件转成html或pdf。

使用过程

引进依赖包

    <!-- swagger工具包 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${swagger.version}</version>
    </dependency>
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger.version}</version>
    </dependency>

在配置 application.yml 中，用于 SwaggerConfig 读取。这样可以控制是否开启(线上环境关闭)

swagger2:
  show: true

配置 Swagger2（注意扫描的包的路径是否正确，否则会显示不了数据）

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Value("${swagger2.show}")
    private boolean swagger2Show;

    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swagger2Show)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zeffon.esave"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-bootstrap-ui RESTful APIs")
                .version("1.0")
                .build();
    }
}

在 API 类和方法上加注解

@Api(value = "解锁日志")
@RestController
@RequestMapping("/log")
public class UnlockLogAPI {

    private final UnlockLogService unlockLogService;

    @Autowired
    public UnlockLogAPI(UnlockLogService unlockLogService) {
        this.unlockLogService = unlockLogService;
    }

    @GetMapping("/listUnlockLog")
    @ApiOperation(value = "获取用户全部解锁记录", notes = "全部解锁记录", tags = "日志")
    public ResultVOUtil listUnlockLog() {
        List<UnlockLogVO> unlockLog = unlockLogService.listUnlockLog();
        return ResultVOUtil.success(unlockLog);
    }
}

实体类和其属性加注解

@Data
@ApiModel(value = "开锁日志", description = "用户每次开锁的记录")
public class UnlockLog extends Base {
    @ApiModelProperty(example = "1", notes = "用户id")
    private Long uid;
}

运行程序，在浏览器中打开http://127.0.0.1:8081/esave/swagger-ui.html#/

注解说明

API	作用范围	使用位置
@ApiModel	描述返回对象的意义	用在返回对象类上

Spring REST Docs

介绍

Spring REST Docs 的目标替代 SpringFox Swagger，帮助自动化生成 RESTful 服务的文档。
使用 Asciidoctor 编写的手写文档；Spring REST Docs 为 RESTful 服务生成准确且可读的文档。
将手写文档与使用 Spring 测试生成的文档片段相结合。
不受 Swagger 等工具生成的文档的限制。
它可以生成准确，简洁和结构良好的 API 文档。
Spring REST Docs 支持测试驱动 Test Driven。
Spring REST Docs 支持 Spring MVC Test 框架，Spring WebFlux 的 WebTestClient 或 REST Assured 3 测试驱动。
Spring Boot 提供了注解@AutoConfigureRestDocs 简化文档开发。

使用过程（未完待续）

引进依赖包

    <dependency>
        <groupId>org.springframework.restdocs</groupId>
        <artifactId>spring-restdocs-mockmvc</artifactId>
        <version>2.0.2.RELEASE</version>
        <scope>test</scope>
    </dependency>

注解说明

总结

Swagger2 的定位是和应用一起启动的在线文档，文档的浏览者可以很简单的填写表单并发起一个真实的请求，而 Spring REST Docs 更倾向于导出一份离线文档作为展示，并配合 curl、httpie 这种工具请求真实部署的服务。
Swagger2 最大的特点是使用简单，只需要在源码中增加一些描述性的注解即可完成整份文档，而使用 Spring REST Docs 的前提条件是需要在项目中对API进行单元测试。除了依赖，还需要严格的编写 Test 测试代码，保证测试代码通过。但是 Spring REST Docs 生成的文档比较符合于测试团队。

Swagger2 的使用​

介绍​

使用过程​

注解说明​

Spring REST Docs​

介绍​

使用过程（未完待续）​

注解说明​

总结​

文献参考​

Swagger2 的使用

介绍

使用过程

注解说明

Spring REST Docs

介绍

使用过程（未完待续）

注解说明

总结

文献参考