Spring Boot 3.x- RESTful API集成SpringDoc&Swagger-UI

系列文章目录

系列文章:Spring Boot 3.x 系列教程

---

---

前言

springdoc-openapi 帮助使用Spring Boot项目自动化API文档的生成。springdoc-openapi的工作原理是在运行时检查应用程序，根据Spring配置、类结构和各种注释推断API语义。
自动生成JSON/YAML和HTML格式的API文档。这个文档可以通过使用swagger-api注解来完成。

官方网站：springdoc.org

由于Spring Boot 3使用的是Jakarta EE 9，对应的springdoc版本需要升级到v2,目前里程碑M2版本。支持以下内容：

• OpenAPI 3
• Spring-boot v3 (Java 17 & Jakarta EE 9)
• JSR-303 特别注解 @NotNull, @Min, @Max, 和 @Size.
• Swagger-ui
• OAuth 2
• GraalVM native images

Swagger2已经在17年停止维护了，取而代之的是 Swagger3（基于OpenAPI 3),OpenApi是业界真正的 api 文档标准，其是由 Swagger 来维护。

这是一个基于社区的项目，不是由Spring Framework贡献者(Pivotal)维护的。

---

一、快速开始

为了集成spring-boot和swagger-ui，将下列依赖添加到你项目即可(不需要额外的配置)。

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.0.0-M2</version>
   </dependency>

这样自动将swagger-ui部署到一个spring-boot应用程序:

1. 使用官方的swagger-ui jar，可以获得HTML格式的文档

2. Swagger UI页面地址http://server:port/context-path/swagger-ui.html，OpenAPI描述将在以下json格式的url上可用:http://server:port/context-path/v3/api-docs。

例如：http://localhost:8080/swagger-ui.html http://localhost:8080/v3/-api-docs

4. 文档也可以以yaml格式提供，位于以下路径:/v3/api-docs.yaml

对于HTML格式的swagger文档的自定义路径，在spring-boot配置文件中添加一个自定义springdoc属性:。
springdoc.swagger-ui.path=/swagger-ui.html

二、Springdoc-openapi模块

Spring WebMvc支持

<dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
      <version>2.0.0-M2</version>
   </dependency>

Spring WebFlux 支持

 <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
      <version>2.0.0-M2</version>
   </dependency>

三、Restful Api服务集成

本节已Spring Boot3 Restful Api服务为例集成。

1.在原有项目基础上加入 SpringDoc webmvc依赖
2.启动项目
3.访问http://localhost:8080/swagger-ui/index.html

基础配置

1.接口文档全局基础信息配置。

/**
 * spring doc配置
 */
@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI restfulOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Spring Boot3 Restful Zoo API")
                        .description("Zoo & Animal Detail APi")
                        .version("v0.0.1")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("SpringDoc Wiki Documentation")
                        .url("https://springdoc.org/v2"));
    }

}

2.重启项目，接口文档展示具体的描述以及开源协议和wiki地址。

3.接口描述和字段描述
默认情况下接口的功能描述和参数以及字段描述都为空，需要添加对应的注解SpringDoc才能解析：

在swagger2中SpringFox项目使用非常广泛，它也是让spring boot项目快速的集成swagger。目前此项目已经停止更新。那么他们直接注解的对应关系如下：

@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden

@ApiImplicitParam → @Parameter

@ApiImplicitParams → @Parameters

@ApiModel → @Schema

@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)

@ApiModelProperty → @Schema

@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")

@ApiParam → @Parameter

@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

下面已ZooController为例：

@Tag 描述整个Controller

@Tag(name = "ZooController", description = "动物园API")
@RestController
@RequestMapping("/zoos")
public class ZooController {}

@Operation描述具体接口信息，@Parameter描述参数信息 @ApiResponse 接口响应描述信息

  //描述具体接口信息，参数信息
    @Operation(summary = "获取动物园详情", description = "返回单个对象",
            parameters = {@Parameter(name = "id", description = "动物园id")})
    @ApiResponse(responseCode = "2xx",description = "动物园实体对象")
    @SneakyThrows
    @GetMapping(value = "/{id}")
    public ResponseEntity<ZooResponse> detail(@PathVariable("id") Integer id) {

        return ResponseEntity.ok(zooService.detail(id));
    }

@Schema 描述对象信息

@Data
@NoArgsConstructor
@AllArgsConstructor
@Schema(name = "ZooResponse", title = "动物园对象")
public class ZooResponse implements Serializable {
    @Schema(title = "动物园id")
    private Integer id;
    @Schema(title = "动物园名称")
    private String name;
    @Schema(title = "动物园地址")
    private String address;
    @Schema(title = "动物园电话")
    private String telephone;
}

---

总结

SpringDoc集成Swagger到Spring Boot3 非常的方便，目前2者都是m2版本，等待最终GA版本。