iailab-plat.git

dongyukun

2024-12-31 6eeac9efdb16f92d19536bf23a2d1471705fe752

提交 \| 用户 \| 时间
e7c126	1	package com.iailab.framework.swagger.config;
H	2
	3	import io.swagger.v3.oas.models.Components;
	4	import io.swagger.v3.oas.models.OpenAPI;
	5	import io.swagger.v3.oas.models.info.Contact;
	6	import io.swagger.v3.oas.models.info.Info;
	7	import io.swagger.v3.oas.models.info.License;
	8	import io.swagger.v3.oas.models.media.IntegerSchema;
	9	import io.swagger.v3.oas.models.media.StringSchema;
	10	import io.swagger.v3.oas.models.parameters.Parameter;
	11	import io.swagger.v3.oas.models.security.SecurityRequirement;
	12	import io.swagger.v3.oas.models.security.SecurityScheme;
	13	import org.springdoc.core.*;
	14	import org.springdoc.core.customizers.OpenApiBuilderCustomizer;
	15	import org.springdoc.core.customizers.ServerBaseUrlCustomizer;
	16	import org.springdoc.core.providers.JavadocProvider;
	17	import org.springframework.boot.autoconfigure.AutoConfiguration;
	18	import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
	19	import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
	20	import org.springframework.boot.context.properties.EnableConfigurationProperties;
	21	import org.springframework.context.annotation.Bean;
	22	import org.springframework.context.annotation.Primary;
	23	import org.springframework.http.HttpHeaders;
	24
	25	import java.util.HashMap;
	26	import java.util.List;
	27	import java.util.Map;
	28	import java.util.Optional;
	29
	30	import static com.iailab.framework.web.core.util.WebFrameworkUtils.HEADER_TENANT_ID;
	31
	32	/**
	33	* Swagger 自动配置类，基于 OpenAPI + Springdoc 实现。
	34	*
	35	* 友情提示：
	36	* 1. Springdoc 文档地址：<a href="https://github.com/springdoc/springdoc-openapi">仓库</a>
	37	* 2. Swagger 规范，于 2015 更名为 OpenAPI 规范，本质是一个东西
	38	*
	39	* @author iailab
	40	*/
	41	@AutoConfiguration
	42	@ConditionalOnClass({OpenAPI.class})
	43	@EnableConfigurationProperties(SwaggerProperties.class)
	44	@ConditionalOnProperty(prefix = "springdoc.api-docs", name = "enabled", havingValue = "true", matchIfMissing = true) // 设置为 false 时，禁用
	45	public class IailabSwaggerAutoConfiguration {
	46
	47	// ========== 全局 OpenAPI 配置 ==========
	48
	49	@Bean
	50	public OpenAPI createApi(SwaggerProperties properties) {
	51	Map<String, SecurityScheme> securitySchemas = buildSecuritySchemes();
	52	OpenAPI openAPI = new OpenAPI()
	53	// 接口信息
	54	.info(buildInfo(properties))
	55	// 接口安全配置
	56	.components(new Components().securitySchemes(securitySchemas))
	57	.addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION));
	58	securitySchemas.keySet().forEach(key -> openAPI.addSecurityItem(new SecurityRequirement().addList(key)));
	59	return openAPI;
	60	}
	61
	62	/**
	63	* API 摘要信息
	64	*/
	65	private Info buildInfo(SwaggerProperties properties) {
	66	return new Info()
	67	.title(properties.getTitle())
	68	.description(properties.getDescription())
	69	.version(properties.getVersion())
	70	.contact(new Contact().name(properties.getAuthor()).url(properties.getUrl()).email(properties.getEmail()))
	71	.license(new License().name(properties.getLicense()).url(properties.getLicenseUrl()));
	72	}
	73
	74	/**
	75	* 安全模式，这里配置通过请求头 Authorization 传递 token 参数
	76	*/
	77	private Map<String, SecurityScheme> buildSecuritySchemes() {
	78	Map<String, SecurityScheme> securitySchemes = new HashMap<>();
	79	SecurityScheme securityScheme = new SecurityScheme()
	80	.type(SecurityScheme.Type.APIKEY) // 类型
	81	.name(HttpHeaders.AUTHORIZATION) // 请求头的 name
	82	.in(SecurityScheme.In.HEADER); // token 所在位置
	83	securitySchemes.put(HttpHeaders.AUTHORIZATION, securityScheme);
	84	return securitySchemes;
	85	}
	86
	87	/**
	88	* 自定义 OpenAPI 处理器
	89	*/
	90	@Bean
	91	@Primary // 目的：以我们创建的 OpenAPIService Bean 为主，避免一键改包后，启动报错！
	92	public OpenAPIService openApiBuilder(Optional<OpenAPI> openAPI,
	93	SecurityService securityParser,
	94	SpringDocConfigProperties springDocConfigProperties,
	95	PropertyResolverUtils propertyResolverUtils,
	96	Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomizers,
	97	Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomizers,
	98	Optional<JavadocProvider> javadocProvider) {
	99
	100	return new OpenAPIService(openAPI, securityParser, springDocConfigProperties,
	101	propertyResolverUtils, openApiBuilderCustomizers, serverBaseUrlCustomizers, javadocProvider);
	102	}
	103
	104	// ========== 分组 OpenAPI 配置 ==========
	105
	106	/**
	107	* 所有模块的 API 分组
	108	*/
	109	@Bean
	110	public GroupedOpenApi allGroupedOpenApi() {
	111	return buildGroupedOpenApi("all", "");
	112	}
	113
	114	public static GroupedOpenApi buildGroupedOpenApi(String group) {
	115	return buildGroupedOpenApi(group, group);
	116	}
	117
	118	public static GroupedOpenApi buildGroupedOpenApi(String group, String path) {
	119	return GroupedOpenApi.builder()
	120	.group(group)
	121	.pathsToMatch("/admin-api/" + path + "/", "/app-api/" + path + "/")
	122	.addOperationCustomizer((operation, handlerMethod) -> operation
	123	.addParametersItem(buildTenantHeaderParameter())
	124	.addParametersItem(buildSecurityHeaderParameter()))
	125	.build();
	126	}
	127
	128	/**
	129	* 构建 Tenant 租户编号请求头参数
	130	*
	131	* @return 多租户参数
	132	*/
	133	private static Parameter buildTenantHeaderParameter() {
	134	return new Parameter()
	135	.name(HEADER_TENANT_ID) // header 名
	136	.description("租户编号") // 描述
	137	.in(String.valueOf(SecurityScheme.In.HEADER)) // 请求 header
	138	.schema(new IntegerSchema()._default(1L).name(HEADER_TENANT_ID).description("租户编号")); // 默认：使用租户编号为 1
	139	}
	140
	141	/**
	142	* 构建 Authorization 认证请求头参数
	143	*
	144	* 解决 Knife4j <a href="https://gitee.com/xiaoym/knife4j/issues/I69QBU">Authorize 未生效，请求header里未包含参数</a>
	145	*
	146	* @return 认证参数
	147	*/
	148	private static Parameter buildSecurityHeaderParameter() {
	149	return new Parameter()
	150	.name(HttpHeaders.AUTHORIZATION) // header 名
	151	.description("认证 Token") // 描述
	152	.in(String.valueOf(SecurityScheme.In.HEADER)) // 请求 header
	153	.schema(new StringSchema()._default("Bearer test1").name(HEADER_TENANT_ID).description("认证 Token")); // 默认：使用用户编号为 1
	154	}
	155
	156	}
	157