整合Spring Boot 3.x与OpenAPI 3(Swagger3)配置详解

在Spring Boot 3项目中集成了Swagger 3，不再使用SpringFox，而是集成了基于OpenAPI 3的SpringDoc在线生成API文档。

OpenAPI 3规范是一种易于阅读和理解、跨平台和语言、提高协作效率、提供API管理和监控的RESTful API文档规范，提高了API设计和开发的效率、可重用性和互操作性。

本文章示例基于Spring Boot 3.3.0版本，配置方法适合所有Spring Boot 3.x版本。

1. Spring WebMvc项目配置

如果您是Spring WebMvc项目，则用“springdoc-openapi-starter-webmvc-api”，如下所示:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.3.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.5.0</version>
</dependency>

其中，Swagger2和OpenAPI3相关的注解映射关系参考如下：

@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 = "test", notes = "test xxx") → @Operation(summary = "test", description = "test xxx")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "404 error") → @ApiResponse(responseCode = "404", description = "404 error")

添加完包依赖之后，您还需要在配置“application.yml”文件中配置接口文档访问地址等配置信息，如下所示：

springdoc:
  api-docs:
    enabled: true
    path: /api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html

除此之外，您还可以进行其他配置，如group-configs等，详细配置见官方文档。

示例运行结果如下图所示：

与Swagger2一样，您可以构建OpenAPI 3配置类，如下示例代码所示：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI swaggerOpenApi(){
        return new OpenAPI()
                .info(new Info().title("XX系统")
                        .contact(new Contact())
                        .description("XX系统WebAPI文档")
                        .version("v1"));
    }
}

示例运行结果如下图所示：

2. knife4j配置

如果您习惯使用knife4j文档界面，则直接引用“knife4j-openapi3-jakarta-spring-boot-starter”包即可，如下所示：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

您还可以在配置文件“application.yml”中进行knife4j增强配置，也可以默认不进行任何配置。knife4j增强配置示例如下所示：

knife4j:
  enable: true
  setting:
    language: zh_cn
  basic:
    enable: true
    # Basic认证用户名
    username: test
    # Basic认证密码
    password: 123456

3. Spring WebFlux项目配置

如果您是Spring WebFlux项目，则用“springdoc-openapi-starter-webflux-ui”，如下所示:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
    <version>3.3.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.5.0</version>
</dependency>

最后，建议生产环境尽量关闭API接口文档。

#头条创作挑战赛##spring boot#

Tags：apiimplicitparam注解用法