整合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”，如下所示:

    org.springframework.boot
    spring-boot-starter-web
    3.3.0


    org.springdoc
    springdoc-openapi-starter-webmvc-api
    2.5.0

其中，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”包即可，如下所示：

    com.github.xiaoymin
    knife4j-openapi3-jakarta-spring-boot-starter
    4.5.0

您还可以在配置文件“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”，如下所示:

    org.springframework.boot
    spring-boot-starter-webflux
    3.3.0


    org.springdoc
    springdoc-openapi-starter-webflux-ui
    2.5.0

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

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