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#/

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

Swagger 运行效果

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才是通向未来的正确选择。

标签: