SpringBoot集成Swagger

package com.example.swaggerdemo.config; import io.swagger.annotations.ApiOperation; import org.springframework.beans.factory.annotation.Value; import org.springframework.boot.actuate.autoconfigure.endpoint.web.CorsEndpointProperties; import org.springframework.boot.actuate.autoconfigure.endpoint.web.WebEndpointProperties; import org.springframework.boot.actuate.autoconfigure.web.server.ManagementPortType; import org.springframework.boot.actuate.endpoint.ExposableEndpoint; import org.springframework.boot.actuate.endpoint.web.*; import org.springframework.boot.actuate.endpoint.web.annotation.ControllerEndpointsSupplier; import org.springframework.boot.actuate.endpoint.web.annotation.ServletEndpointsSupplier; import org.springframework.boot.actuate.endpoint.web.servlet.WebMvcEndpointHandlerMapping; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.env.Environment; import org.springframework.util.StringUtils; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.oas.annotations.EnableOpenApi; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import java.util.ArrayList; import java.util.Collection; import java.util.List; /** * @Author yrz * @create 2023/7/17 10:59 * @Description TODO */ /** * 在早期版本的Swagger中，常常要求将@EnableSwagger2注解放置在Spring Boot应用的启动类上。但是，从Swagger 3.0开始，其对注解的使用进行了一些调整。 * 对于Swagger 3.0及更高版本，我们需要使用其他注解来启用Swagger API文档框架。具体而言，我们可以使用以下注解之一： * - @EnableSwagger2WebMvc：如果我们使用Spring MVC作为Web框架，则可以将此注解放置在配置类上，来启用Swagger。 * - @EnableSwagger2WebFlux：如果我们使用Spring WebFlux作为Web框架，则可以将此注解放置在配置类上，来启用Swagger。 * - @EnableOpenApi：这是Swagger 3.0引入的新注解，可以用于Spring Boot应用中启用Swagger。它可以用于既支持Spring MVC，也支持Spring WebFlux的应用。 * 因此，根据你的具体情况，你可以选择适当的注解来启用Swagger API文档框架，并将其放置在合适的配置类上。 */ @EnableOpenApi @Configuration public class SwaggerConfig { @Value("${base.url}") private String contextPath; @Bean public CustomSwaggerUiConfig swaggerUiConfig() { return new CustomSwaggerUiConfig(contextPath); } @Bean public Docket createRestApi() { /** * 在Swagger中，Docket是Swagger的主要配置类，它用于初始化和配置Swagger的核心功能。在Docket初始化时， * 可以设置DocumentationType值来指定生成的API文档的类型和格式。 * DocumentationType是一个枚举类型，它定义了几种不同的API文档标准。常见的DocumentationType值及其含义如下： * 1. SWAGGER_2：表示使用Swagger 2规范（旧版Swagger）生成API文档。这是Swagger默认的文档类型，生成的文档将符合Swagger 2的规范。 * 2. OPENAPI_3_0_0：表示使用OpenAPI 3规范（Swagger的最新规范）生成API文档。OpenAPI是Swagger 3版本开始使用的新规范，具有更多功能和灵活性。 * 一般来说，如果使用较新版本的Swagger（3.0及以上），建议使用OPENAPI_3_0_0作为DocumentationType的值。如果使用早期版本的Swagger（2.0），则使用SWAGGER_2。 * 通过设置DocumentationType的值，我们可以确保生成的API文档符合相应的规范，以便开发者更好地理解和使用API。 */ return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.any()) .build(); } /** * ApiInfo类是Swagger API文档框架中的一个辅助类，用于提供API文档的基本信息，包括标题、描述、版本号、许可证等。 * ApiInfo类的作用是为API文档提供更详细的介绍和说明。通过配置ApiInfo，我们可以在生成的API文档中添加以下信息： * 1. 标题（Title）：用于标识API文档的名称或标题。 * 2. 描述（Description）：对API文档的简要描述，可以说明API的功能、用途、使用方式等。 * 3. 版本（Version）：API文档的版本号，用于标识API的不同版本。 * 4. 许可证（License）：API文档所属的许可证类型，可以指明API的开放程度、使用限制等。 * 5. 作者信息（Contact）：关于API的作者或维护者的联系信息，如姓名、电子邮件等。 * 6. 参考链接（Terms of service URL）：提供一条指向API相关信息或条款的链接。 * 通过配置ApiInfo类，我们可以向API文档添加更多详细信息，方便开发者理解和使用API。这些信息将在Swagger的可视化界面中显示，并提供给开发者参考和查阅。 * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Swagger接口文档") .description("如有疑问，请联系开发工程师") .contact(new Contact("yrz", "", "yrz@qq.com.cn")) .version("1.0") .build(); } /** * 增加如下配置可解决Spring Boot与Swagger 3.0.0 不兼容问题 **/ @Bean public WebMvcEndpointHandlerMapping webEndpointServletHandlerMapping(WebEndpointsSupplier webEndpointsSupplier, ServletEndpointsSupplier servletEndpointsSupplier, ControllerEndpointsSupplier controllerEndpointsSupplier, EndpointMediaTypes endpointMediaTypes, CorsEndpointProperties corsProperties, WebEndpointProperties webEndpointProperties, Environment environment) { List<ExposableEndpoint<?>> allEndpoints = new ArrayList(); Collection<ExposableWebEndpoint> webEndpoints = webEndpointsSupplier.getEndpoints(); allEndpoints.addAll(webEndpoints); allEndpoints.addAll(servletEndpointsSupplier.getEndpoints()); allEndpoints.addAll(controllerEndpointsSupplier.getEndpoints()); String basePath = webEndpointProperties.getBasePath(); EndpointMapping endpointMapping = new EndpointMapping(basePath); boolean shouldRegisterLinksMapping = this.shouldRegisterLinksMapping(webEndpointProperties, environment, basePath); return new WebMvcEndpointHandlerMapping(endpointMapping, webEndpoints, endpointMediaTypes, corsProperties.toCorsConfiguration(), new EndpointLinksResolver(allEndpoints, basePath), shouldRegisterLinksMapping, null); } private boolean shouldRegisterLinksMapping(WebEndpointProperties webEndpointProperties, Environment environment, String basePath) { return webEndpointProperties.getDiscovery().isEnabled() && (StringUtils.hasText(basePath) || ManagementPortType.get(environment).equals(ManagementPortType.DIFFERENT)); } }