springcloud-gateway集成knife4j（swagger2）
-
springcloud-gateway集成knife4j（swagger2）
- 環(huán)境信息
- 準(zhǔn)備工作
-
微服務(wù)集成knife4j
- 第一步：編寫Knife4jApiInfoProperties
- 第二步：編寫配置類Knife4jConfig
- 第三步：放行相關(guān)資源 & 保證啟動了knife4j
-
網(wǎng)關(guān)集成knife4j
- 編寫配置類Knife4jGatewayConfig
- 測試驗證
- 相關(guān)資料
環(huán)境信息
- spring-boot：2.6.3
- spring-cloud-alibaba：2021.0.1.0
- knife4j-openapi2-spring-boot-starter：4.0.0
準(zhǔn)備工作
各微服務(wù)&網(wǎng)關(guān)引入依賴
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
<version>4.0.0</version>
</dependency>
微服務(wù)集成knife4j
第一步：編寫Knife4jApiInfoProperties
import com.ideaaedi.springcloud.jd.commonspring.config.Knife4jConfig;
import lombok.Data;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
/**
* api 基礎(chǔ)信息配置。更多配置信息項見{@link Knife4jConfig}
*
* @author <font size = "20" color = "#3CAA3C"><a >JustryDeng</a></font> <img
* src="https://gitee.com/JustryDeng/shared-files/raw/master/JustryDeng/avatar.jpg" />
* @since 2021.0.1.D
*/
@Data
@Component
public class Knife4jApiInfoProperties {
/**
* 要掃描api的base包
*/
@Value("${api-info.base-package:com}")
private String basePackage;
/**
* 是否啟用登錄認(rèn)證
*/
@Value("${api-info.enable-security:true}")
private boolean enableSecurity;
/**
* 文檔標(biāo)題
*/
@Value("${api-info.title:}")
private String title;
/**
* 文檔描述
*/
@Value("${api-info.description:api info}")
private String description;
/**
* 文檔版本
*/
@Value("${api-info.version:1.0.0}")
private String version;
/**
* 聯(lián)系人姓名
*/
@Value("${api-info.contact-name:JustryDeng}")
private String contactName;
/**
* 聯(lián)系人網(wǎng)址
*/
@Value("${api-info.contact-url:https://gitee.com/JustryDeng/projects}")
private String contactUrl;
/**
* 聯(lián)系人郵箱
*/
@Value("${api-info.contact-email:13548417409@163.com}")
private String contactEmail;
}
第二步：編寫配置類Knife4jConfig
import com.fasterxml.jackson.databind.introspect.BeanPropertyDefinition;
import com.ideaaedi.springcloud.jd.commonds.constant.BaseConstant;
import com.ideaaedi.springcloud.jd.commonds.support.EnumDescriptor;
import com.ideaaedi.springcloud.jd.commonspring.config.properties.Knife4jApiInfoProperties;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiParam;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.lang.NonNull;
import org.springframework.lang.Nullable;
import org.springframework.stereotype.Component;
import org.springframework.util.CollectionUtils;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ModelPropertyBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.Contact;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.schema.ModelPropertyBuilderPlugin;
import springfox.documentation.spi.schema.contexts.ModelPropertyContext;
import springfox.documentation.spi.service.ParameterBuilderPlugin;
import springfox.documentation.spi.service.contexts.ParameterContext;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import java.lang.reflect.Field;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Objects;
import java.util.Optional;
import java.util.stream.Collectors;
/**
* knife4j配置類
*
* @author <font size = "20" color = "#3CAA3C"><a >JustryDeng</a></font> <img
* src="https://gitee.com/JustryDeng/shared-files/raw/master/JustryDeng/avatar.jpg" />
* @since 2021.0.1.D
*/
@Slf4j
@Configuration
public class Knife4jConfig implements WebMvcConfigurer {
/**
* 文檔相關(guān)資源的鏈接（需保證這些資源不需要鑒權(quán)即可訪問）
*/
public static String[] RESOURCE_URLS = new String[]{"/webjars/**", "/swagger**", "/v2/api-docs", "/doc.html"};
@Value("${spring.application.name:}")
private String applicationName;
@Bean
public Docket docket(Knife4jApiInfoProperties knife4jApiInfoProperties) {
String apiBasePackage = knife4jApiInfoProperties.getBasePackage();
Docket docket =
new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo(knife4jApiInfoProperties)).select().apis(RequestHandlerSelectors.basePackage(apiBasePackage)).paths(PathSelectors.any()).build();
if (knife4jApiInfoProperties.isEnableSecurity()) {
docket.securitySchemes(securitySchemes()).securityContexts(securityContexts());
}
return docket;
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
private ApiInfo apiInfo(Knife4jApiInfoProperties knife4jApiInfoProperties) {
return new ApiInfoBuilder().title(knife4jApiInfoProperties.getTitle()).description(knife4jApiInfoProperties.getDescription()).termsOfServiceUrl(StringUtils.isBlank(applicationName) ? "" : "/" + applicationName).contact(new Contact(knife4jApiInfoProperties.getContactName(), knife4jApiInfoProperties.getContactUrl(), knife4jApiInfoProperties.getContactEmail())).version(knife4jApiInfoProperties.getVersion()).build();
}
private List<SecurityScheme> securitySchemes() {
// 設(shè)置請求頭信息
List<SecurityScheme> result = new ArrayList<>();
// 第一個參數(shù)name，自定義即可。 在配置securityContexts時，通過此name對應(yīng)到apiKey即可
// 第二個參數(shù)，header name自定義即可。 如：BaseConstant.JWT_TOKEN_KEY=Auth-Token，然后在代碼里request.getHeader(BaseConstant.JWT_TOKEN_KEY)取值
ApiKey apiKey = new ApiKey("JustryDengApiKey", BaseConstant.JWT_TOKEN_KEY, "header");
result.add(apiKey);
return result;
}
private List<SecurityContext> securityContexts() {
// 設(shè)置需要登錄認(rèn)證的路徑
List<SecurityContext> result = new ArrayList<>();
List<SecurityReference> securityReferences = defaultAuth();
result.add(
SecurityContext.builder().securityReferences(securityReferences).forPaths(
// 當(dāng)直接使用swagger文檔發(fā)送請求時，這些api需要滿足securityReferences認(rèn)證要求
PathSelectors.regex("/*/.*")
.and(
// 當(dāng)直接使用swagger文檔發(fā)送請求時，這些api不需要滿足securityReferences認(rèn)證要求. '.*'表示匹配所有
PathSelectors.regex("/sys-login/.*").or(PathSelectors.regex("/tmp.*"))
.negate()
)
).build()
);
return result;
}
private List<SecurityReference> defaultAuth() {
List<SecurityReference> result = new ArrayList<>();
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
// 這里指定使用哪個apiKey進(jìn)行認(rèn)證鑒權(quán). 這里指定使用上面名為JustryDengApiKey的apiKey
result.add(new SecurityReference("JustryDengApiKey", authorizationScopes));
return result;
}
/**
* 顯示自定義枚舉類型注釋
* <p>
* <br/> 參考<a
* href="https://blog.gelu.me/2021/Knife4j-Swagger%E8%87%AA%E5%AE%9A%E4%B9%89%E6%9E%9A%E4%B8%BE%E7%B1%BB%E5%9E%8B
* /">here</a>
*/
@Component
@SuppressWarnings("unchecked")
public static class Knife4jSwaggerEnumPlugin implements ModelPropertyBuilderPlugin, ParameterBuilderPlugin {
private static final Field parameterDescriptionField;
private static final Field modelPropertyBuilderDescriptionField;
static {
// swagger3用: parameterDescriptionField = ReflectionUtils.findField(RequestParameterBuilder.class, "description");
parameterDescriptionField = ReflectionUtils.findField(ParameterBuilder.class, "description");
Objects.requireNonNull(parameterDescriptionField, "parameterDescriptionField should noe be null.");
ReflectionUtils.makeAccessible(parameterDescriptionField);
// swagger3用: modelPropertyBuilderDescriptionField = ReflectionUtils.findField(PropertySpecificationBuilder.class, "description");
modelPropertyBuilderDescriptionField = ReflectionUtils.findField(ModelPropertyBuilder.class, "description");
Objects.requireNonNull(modelPropertyBuilderDescriptionField, "ModelPropertyBuilder_descriptionField should noe be null.");
ReflectionUtils.makeAccessible(modelPropertyBuilderDescriptionField);
}
/**
* {@link ApiModelProperty}相關(guān)
* <p>
* 主要處理枚舉對象直接作為方法參數(shù)的內(nèi)部字段的情況. 如：
* <pre>
* @Data
* public class LoginTokenRespVO {
*
* @ApiModelProperty("用戶類型")
* private UserTypeEnum userType;
* }
* </pre>
*/
@Override
public void apply(ModelPropertyContext context) {
Optional<BeanPropertyDefinition> optional = context.getBeanPropertyDefinition();
if (!optional.isPresent()) {
return;
}
// 對應(yīng)被@ApiModelProperty標(biāo)注的字段
BeanPropertyDefinition beanPropertyDefinition = optional.get();
Class<?> fieldType = beanPropertyDefinition.getField().getRawType();
if (!Enum.class.isAssignableFrom(fieldType)) {
return;
}
Class<Enum<?>> enumType = (Class<Enum<?>>) fieldType;
Enum<?>[] enumConstants = enumType.getEnumConstants();
// swagger3用: PropertySpecificationBuilder modelPropertyBuilder = context.getSpecificationBuilder();
ModelPropertyBuilder modelPropertyBuilder = context.getBuilder();
Object oldValue = ReflectionUtils.getField(modelPropertyBuilderDescriptionField, modelPropertyBuilder);
// 解析枚舉
List<String> enumDescList =
Arrays.stream(enumConstants).map(this::obtainEnumDescription).collect(Collectors.toList());
/*
* swagger3用:
* modelPropertyBuilder.description((oldValue == null ? BaseConstant.EMPTY : oldValue) + buildHtmlUnOrderList(enumDescList))
* .type(new ModelSpecificationBuilder().scalarModel(ScalarType.UUID).build());
*/
modelPropertyBuilder.description((oldValue == null ? BaseConstant.EMPTY : oldValue) + buildHtmlUnOrderList(enumDescList))
.type(context.getResolver().resolve(Enum.class));
}
/**
* {@link ApiParam}、{@link io.swagger.v3.oas.annotations.Parameter}相關(guān).
* <p> 主要處理：枚舉對象直接作為方法參數(shù)的情況. 如：
* <pre>
* @PostMapping("/test1")
* @ApiOperation(value = "測試1")
* public void test1(@ApiParam(value = "用戶類型", required = true) UserTypeEnum userTypeEnum)
* </pre>
*/
@Override
public void apply(ParameterContext context) {
Class<?> type = context.resolvedMethodParameter().getParameterType().getErasedType();
// swagger3用: RequestParameterBuilder parameterBuilder = context.requestParameterBuilder();
ParameterBuilder parameterBuilder = context.parameterBuilder();
if (!Enum.class.isAssignableFrom(type)) {
return;
}
Class<Enum<?>> enumType = (Class<Enum<?>>) type;
Enum<?>[] enumConstants = enumType.getEnumConstants();
// 解析枚舉
List<String> enumDescList = Arrays.stream(enumConstants).map(this::obtainEnumDescription).collect(Collectors.toList());
Object oldValue = ReflectionUtils.getField(parameterDescriptionField, parameterBuilder);
parameterBuilder.description((oldValue == null ? BaseConstant.EMPTY : oldValue) + buildHtmlUnOrderList(enumDescList));
}
/**
* 此插件是否支持處理該DocumentationType
*/
@Override
public boolean supports(DocumentationType documentationType) {
return true;
}
/**
* 獲取枚舉描述
*
* @param enumObj 枚舉對象
*
* @return 枚舉描述
*/
private String obtainEnumDescription(@NonNull Enum<?> enumObj) {
String name = enumObj.name();
/*
* 枚舉說明器示例:
*
* public interface EnumDescriptor {
* // 獲取枚舉項說明
* String obtainDescription();
* }
*/
if (enumObj instanceof EnumDescriptor) {
return name + "：" + ((EnumDescriptor) enumObj).obtainDescription();
}
return name;
}
/**
* 構(gòu)建無序列表html
*
* @param itemList 列表元素
*
* @return 無序列表html
*/
private String buildHtmlUnOrderList(@Nullable List<String> itemList) {
if (CollectionUtils.isEmpty(itemList)) {
return BaseConstant.EMPTY;
}
StringBuilder sb = new StringBuilder();
sb.append("<ul>");
for (String item : itemList) {
sb.append("<li>");
sb.append(item);
sb.append("</li>");
}
sb.append("</ul>");
return sb.toString();
}
}
}
第三步：放行相關(guān)資源 & 保證啟動了knife4j
-
放行相關(guān)資源
對于管控了權(quán)限的微服務(wù)，應(yīng)放行以下資源
// 需要放行的資源已經(jīng)定義進(jìn)上面編寫的Knife4jConfig中 public static String[] RESOURCE_URLS = new String[]{"/webjars/**", "/swagger**", "/v2/api-docs", "/doc.html"}; -
保證啟動了knife4j
# 啟動knife4j（注：有時，如果我們不進(jìn)行此配置，knife4j不會開啟） # 其實核心是：保證com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration生效即可。如果knife4j怎么也沒啟動，請debug此類，確保其被加載 knife4j.enable=true
網(wǎng)關(guān)集成knife4j
編寫配置類Knife4jGatewayConfig
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.gateway.config.GatewayProperties;
import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.support.NameUtils;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Mono;
import springfox.documentation.swagger.web.SecurityConfiguration;
import springfox.documentation.swagger.web.SecurityConfigurationBuilder;
import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger.web.UiConfigurationBuilder;
import javax.annotation.Resource;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Optional;
import java.util.Set;
import java.util.stream.Collectors;
/**
* 網(wǎng)關(guān)knife4j配置
*
* @author <font size = "20" color = "#3CAA3C"><a >JustryDeng</a></font> <img src="https://gitee.com/JustryDeng/shared-files/raw/master/JustryDeng/avatar.jpg" />
* @since 2021.0.1.D
*/
@RestController
public class Knife4jGatewayConfig {
private final SecurityConfiguration securityConfiguration;
private final UiConfiguration uiConfiguration;
private final SwaggerResourceAdapter swaggerResourceAdapter;
public Knife4jGatewayConfig(@Autowired(required = false) SecurityConfiguration securityConfiguration,
@Autowired(required = false) UiConfiguration uiConfiguration,
SwaggerResourceAdapter swaggerResourceAdapter) {
this.securityConfiguration = securityConfiguration;
this.uiConfiguration = uiConfiguration;
this.swaggerResourceAdapter = swaggerResourceAdapter;
}
/**
* 安全配置
*/
@GetMapping("/swagger-resources/configuration/security")
public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {
return Mono.just(new ResponseEntity<>(
Optional.ofNullable(securityConfiguration).orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK));
}
/**
* ui配置
*/
@GetMapping("/swagger-resources/configuration/ui")
public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {
return Mono.just(new ResponseEntity<>(
Optional.ofNullable(uiConfiguration).orElse(UiConfigurationBuilder.builder().build()), HttpStatus.OK));
}
/**
* 資源配置，自動路由到微服務(wù)中的各個服務(wù)的api-docs信息
*/
@GetMapping("/swagger-resources")
public Mono<ResponseEntity<List<SwaggerResource>>> swaggerResources() {
return Mono.just(new ResponseEntity<>(swaggerResourceAdapter.get(), HttpStatus.OK));
}
/**
* favicon.ico
*/
@GetMapping("/favicon.ico")
public Mono<ResponseEntity<?>> favicon() {
return Mono.just(new ResponseEntity<>(null, HttpStatus.OK));
}
/**
* swagger資源適配器
*
* @author <font size = "20" color = "#3CAA3C"><a >JustryDeng</a></font> <img src="https://gitee.com/JustryDeng/shared-files/raw/master/JustryDeng/avatar.jpg" />
* @since 2021.0.1.D
*/
@Slf4j
@Component
public static class SwaggerResourceAdapter implements SwaggerResourcesProvider {
/**
* spring-cloud-gateway是否開啟了根據(jù)服務(wù)發(fā)現(xiàn)自動為服務(wù)創(chuàng)建router
*/
@Value("${spring.cloud.gateway.discovery.locator.enabled:false}")
private boolean autoCreateRouter;
@Value("${spring.application.name:}")
private String applicationName;
@Resource
private RouteLocator routeLocator;
@Resource
private GatewayProperties gatewayProperties;
/**
* 根據(jù)當(dāng)前所有的微服務(wù)路由信息，創(chuàng)建對應(yīng)的SwaggerResource
*/
@Override
public List<SwaggerResource> get() {
List<SwaggerResource> finalResources;
Set<String> routes = new LinkedHashSet<>(16);
// 獲取所有路由的id
routeLocator.getRoutes().subscribe(route -> {
String routeId = route.getId();
routeId = routeId.replace("ReactiveCompositeDiscoveryClient_", "");
routes.add(routeId);
});
// 沒有開啟自動創(chuàng)建路由，那么走配置文件中配置的路由
if (!autoCreateRouter) {
finalResources = new ArrayList<>(16);
gatewayProperties.getRoutes().stream()
// 過濾出配置文件中定義的路由
.filter(routeDefinition -> routes.contains(routeDefinition.getId())).forEach(route -> {
route.getPredicates().stream()
// 過濾出設(shè)置有Path Predicate的路由
.filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName()))
// 根據(jù)路徑拼接成api-docs路徑,生成SwaggerResource
.forEach(predicateDefinition -> finalResources.add(swaggerResource(route.getId(),
predicateDefinition.getArgs().get(NameUtils.GENERATED_NAME_PREFIX + "0")
// 如果對應(yīng)的微服務(wù)設(shè)置了server.servlet.context-path，那么這里應(yīng)該是{context-path}/v2/api-docs
.replace("**", "v2/api-docs"))));
});
} else {
// 如果對應(yīng)的微服務(wù)設(shè)置了server.servlet.context-path，那么這里應(yīng)該是/{context-path}/v2/api-docs
finalResources = routes.stream().map(routeId -> swaggerResource(routeId, routeId + "/v2/api-docs")).collect(Collectors.toList());
}
List<SwaggerResource> resources = new ArrayList<>(finalResources);
// resources過濾掉網(wǎng)關(guān)的SwaggerResource, 我們一般也不會在網(wǎng)關(guān)中編寫業(yè)務(wù)controller
if (StringUtils.isNotBlank(applicationName)) {
resources = resources.stream().filter(x -> !applicationName.equalsIgnoreCase(x.getName())).collect(Collectors.toList());
}
// 排序
resources.sort(Comparator.comparing(x -> x.getName().length()));
return resources;
}
/**
* 創(chuàng)建swagger資源
*
* @param name
* swagger資源名(注：一般對應(yīng) {路由id})
* @param location
* swagger資源路徑(注：一般對應(yīng) {路由id}/v2/api-docs)
* @return swager資源
*/
private SwaggerResource swaggerResource(String name, String location) {
// 確保首字符不是/
location = location.startsWith("/") ? location.substring(1) : location;
log.info("name:{},location:{}", name, location);
SwaggerResource swaggerResource = new SwaggerResource();
swaggerResource.setName(name);
swaggerResource.setLocation(location);
swaggerResource.setSwaggerVersion("2.0");
return swaggerResource;
}
}
}
測試驗證
啟動微服務(wù)后，訪問{網(wǎng)關(guān)}/doc.html完成驗證文章來源：http://www.zghlxwxcb.cn/news/detail-406240.html
文章來源地址http://www.zghlxwxcb.cn/news/detail-406240.html
相關(guān)資料
- springboot2集成knife4j（swagger2）
- springboot2集成knife4j（swagger3）
- springcloud-gateway集成knife4j（swagger3）
- 在微服務(wù)項目中引入 knife4j
- 本文已被收錄進(jìn)《程序員成長筆記》 ，筆者JustryDeng
到了這里，關(guān)于springcloud-gateway集成knife4j的文章就介紹完了。如果您還想了解更多內(nèi)容，請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！
