Java的Spring doc OpenAPI 3.0时代-码谱记录

摘要

对于RestApi应用来说，文档是其中重要的一环。有很多工具可以生成文档，Swagger无疑是比较优秀的一个，下面将基于OpenAPI 3的规范来讲述如何集成到SpringBoot应用中。

本篇内容对 Spring Boot 1.x 和 Spring Boot 2.x 都适用

快速开始

依赖

借助springdoc-openapi，可以自动生成 OpenAPI 3.0规范文件。在Spring-Boot项目中，引入依赖到pom.xml：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.2.32</version>
</dependency>

规约文件

启动项目后，通过下面的地址来查看生成的 OpenAPI 3.0规约文件：

http://localhost:8080/v3/api-docs/

看到的内容如下，部分内容已经省略。

{
openapi: "3.0.1",
    info: {
    title: "OpenAPI definition",
    version: "v0"
    }
}

修改规约地址

如果想自定义上面的地址，可以在配置文件application.yml中修改：

springdoc:
  api-docs:
    path: /docs

修改以后，通过下面的地址访问：

http://localhost:8080/docs

和上面的地址看到的内容一样。

修改规约格式

默认的规约specification文件是JSON格式，如果需要 yaml格式，可以通过下面的形式获得：

http://localhost:8080/v3/api-docs.yaml

看到的内容如下，部分内容已经省略。

openapi: 3.0.1
info:
  title: OpenAPI definition
  version: v0
servers:
- url: http://localhost:8080
  description: Generated server url

集成 Swagger UI

在生成OpenAPI 3.0规约文件后，当然希望可视化文档。集成 Swagger UI可以方便地进行API的在线演示与操作。

依赖

在Spring-Boot项目中，引入依赖到pom.xml：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.2.32</version>
</dependency>

是的，它上面出现过的。也就是说，只需用引入一个依赖就能完成文档可视化。

查看页面

访问下面的地址：

http://localhost:8080/swagger-ui.html

Swagger UI

如果想修改该地址，可以修改配置文件application.yml：

springdoc:
  swagger-ui:
    path: document.html

然后访问地址：

http://localhost:8080/document.html

当然，这并代表地址被完全修改了，最终地址还是被重定向到了http://localhost:8080/swagger-ui/index.html

但是，你不能直接在浏览器访问如下地址：

http://localhost:8080/swagger-ui/index.html

这会使用 OpenAPI 3.0 默认的示例演示UI界面。

示例代码

产品的Bean可以有如下定义：

@Data
@AllArgsConstructor
public class Product {
    private double price;

    private String name;
}

代码中使用了 lombok来简化开发。

查找商品的Controller可以有如下定义：

@RestController
@RequestMapping("/product")
public class ProductController {

    @GetMapping("/find")
    public Product findProduct(){
        return new Product(9.9,"toy");
    }
}

查看一下生成的文档：

http://localhost:8080/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/

可以访问一下，查看效果。

Maven 插件

如果项目是交付型的，给到外部的是jar包或者docker镜像，无法直接部署项目，则可以考虑 maven plugin 插件springdoc-openapi-maven-plugin，直接生成 json 或者 yaml 格式个OpenAPI规约文件。

下面的配置可以在集成测试阶段，通过 springdoc-openapi 生成规约文件。

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <version>2.1.8.RELEASE</version>
    <executions>
        <execution>
            <id>pre-integration-test</id>
            <goals>
                <goal>start</goal>
            </goals>
        </execution>
        <execution>
            <id>post-integration-test</id>
            <goals>
                <goal>stop</goal>
            </goals>
        </execution>
    </executions>
</plugin>
<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>0.2</version>
    <executions>
        <execution>
            <phase>integration-test</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

当然，还可以自定义某些参数配置：

<plugin>
    <executions>
        .........
    </executions>
    <configuration> 
        <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
        <outputFileName>openapi.json</outputFileName>
        <outputDir>${project.build.directory}</outputDir>
    </configuration>
</plugin>

参数说明：

apiDocsUrl 规约文件的访问地址，默认http://localhost:8080/v3/api-docs
outputFileName 规约文件名称，默认openapi.json
outputDir 规约文件的存储路径，默认${project.build.directory}

基于 JSR-303 自动 Bean 校验

JSR-303定义了多个 Bean 注解，@NotNull, @NotBlank, @Size, @Min等。

springdoc-openapi可以自定识别这些注解，并生成到API文档中。

对于商品信息，有一些基本的规定，通过注解实现的代码：

public class Product {

    @NotBlank
    @Min(1)
    private double price;

    @Size(min = 2, max = 128)
    private String name;
}

将显示内容从 Example value切换到 Schema，可以看到注解规范的内容。

Swagger Schema效果

全局异常处理

通过注解 @ControllerAdvice和@ResponseStatus，可以扩充文档中的状态码：

@RestControllerAdvice
public class GlobalControllerExceptionHandler {

    @ExceptionHandler(ConversionFailedException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ResponseEntity<String> handleConnversion(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.BAD_REQUEST);
    }

    @ExceptionHandler(ProductNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ResponseEntity<String> handleBookNotFound(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }
}

这样，就在文档中定义了 400 和 404 的状态码。

Swagger状态码

结语

使用 springdoc-openapi可以方便地与现有项目集成，生成漂亮的文档。

如果你足够懒，只用添加一个依赖jar包，不需要任何配置，就能自定生成OpenAPI3.0规约文档，并通过 Swagger-ui 显示到页面上。

扁平化的UI设计，比上个版本更舒服。

OpenAPI 3.0也打打扩充了上个版本的功能，使得页面上可以显示更丰富的文档信息。

鉴于如今，springfox不再更新，使用springdoc-openapi才是通向未来的正确选择。

Java的Spring doc OpenAPI 3.0时代

摘要