1 说明
对于 Rest API来说很重要的一部分内容就是文档,Swagger 为我们提供了一套通过代码和注解自动生成文档的方法,这一点对于保证 API 文档的及时性将有很大的帮助。
Swagger是一套基于 OpenAPI 规范(OpenAPI Specification,OAS)构建的开源工具,可以帮助我们设计、构建、记录以及使用 Rest API。
本文档使用版本为:swagger3.0,springboot版本为2.6.3;同时解决了swagger3.0版本的2个问题:(1)解决swagger3.0 head传参失效的问题。(2)解决Spring Boot 2.6.x 与Swagger 3.0.0 不兼容问题。
2 代码实现
pom.xml:
<dependencies>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
</dependencies>
SpringFoxSwaggerConfig.java
package com.module.nacos.consumer.infrastructure.swagger;
import io.swagger.models.auth.In;
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.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.*;
@EnableOpenApi
@Configuration
public class SpringFoxSwaggerConfig {
@Value("${spring.application.name}")
private String PROJECT_NAME;
/**
* 配置基本信息
*
* @return
*/
@Bean
public ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(PROJECT_NAME)
.description("swagger test app restful api")
.termsOfServiceUrl("http://localhost")
.contact(new Contact("SSM", "http://localhost", "ssmshe@gmail.com"))
.version("1.0")
.build();
}
/**
* 配置文档生成最佳实践
*
* @param apiInfo
* @return
*/
@Bean
public Docket createRestApi(ApiInfo apiInfo) {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo)
.groupName("YX")
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
.paths(PathSelectors.any())
.build()
//添加token的参数
.securityContexts(securityContexts())
.securitySchemes(securitySchemes());
}
/* ↓↓↓↓ 解决swagger3.0 head传参失效的问题 ↓↓↓↓ */
private List<SecurityScheme> securitySchemes() {
List<SecurityScheme> securitySchemes = new ArrayList<>();
securitySchemes.add(new ApiKey("Authorization", "Authorization", "header"));
securitySchemes.add(new ApiKey("Accept-Language", "Accept-Language", "header"));
return securitySchemes;
}
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$")).build());
return securityContexts;
}
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope1 = new AuthorizationScope("global", "token");
AuthorizationScope[] authorizationScopes1 = new AuthorizationScope[1];
authorizationScopes1[0] = authorizationScope1;
AuthorizationScope authorizationScope2 = new AuthorizationScope("global", "language");
AuthorizationScope[] authorizationScopes2 = new AuthorizationScope[1];
authorizationScopes2[0] = authorizationScope2;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes1));
securityReferences.add(new SecurityReference("Accept-Language", authorizationScopes2));
return securityReferences;
}
/* ↑↑↑↑ 解决swagger3.0 head传参失效的问题 ↑↑↑↑ */
@SafeVarargs
private final <T> Set<T> hashSet(T... ts) {
if (ts.length > 0) {
return new LinkedHashSet<>(Arrays.asList(ts));
}
return null;
}
/**
* 增加如下配置可解决Spring Boot 6.x 与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));
}
}
NacosConsumerApplication.java
package com.module.nacos.consumer;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.cloud.openfeign.EnableFeignClients;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.oas.annotations.EnableOpenApi;
@EnableOpenApi
@SpringBootApplication
public class NacosConsumerApplication {
public static void main(String[] args){
SpringApplication.run(NacosConsumerApplication.class,args);
System.out.println("$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$");
System.out.println("$ $");
System.out.println("$ NacosConsumerApplication started $");
System.out.println("$ $");
System.out.println("$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$");
}
}
3 验证
swagger访问链接:http://localhost:9010/api/swagger-ui/index.html
点击“Authorize”按钮,弹窗内填写请求头信息,之后正常发起请求即可
4 参考链接
1.https://blog.csdn.net/tiantiandjava/article/details/108604242
2.https://blog.csdn.net/xueyushenzhou/article/details/127091559