feat:新增swagger2文档聚合
袁子龙
parent
01895d1279
commit
ff02ae0b56
|
|
@ -17,6 +17,12 @@
|
|||
|
||||
<dependencies>
|
||||
|
||||
<!-- Swagger -->
|
||||
<dependency>
|
||||
<groupId>io.swagger</groupId>
|
||||
<artifactId>swagger-annotations</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- SpringCloud Openfeign -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,38 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
<parent>
|
||||
<groupId>com.muyu</groupId>
|
||||
<artifactId>cloud-server</artifactId>
|
||||
<version>3.6.3</version>
|
||||
<relativePath>../../pom.xml</relativePath>
|
||||
</parent>
|
||||
|
||||
<groupId>com.muyu</groupId>
|
||||
<artifactId>cloud-common-swagger</artifactId>
|
||||
<description>
|
||||
cloud-common-swagger swagger2文档聚合
|
||||
</description>
|
||||
<properties>
|
||||
<maven.compiler.source>17</maven.compiler.source>
|
||||
<maven.compiler.target>17</maven.compiler.target>
|
||||
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
|
||||
</properties>
|
||||
<dependencies>
|
||||
<!-- SpringBoot Web -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-web</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- Swagger -->
|
||||
<dependency>
|
||||
<groupId>io.springfox</groupId>
|
||||
<artifactId>springfox-swagger2</artifactId>
|
||||
<version>${swagger.fox.version}</version>
|
||||
</dependency>
|
||||
|
||||
</dependencies>
|
||||
</project>
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
package com.muyu.common.swagger.annotation;
|
||||
|
||||
/**
|
||||
* @author 袁子龙
|
||||
* @package：com.muyu.common.swagger.annotation
|
||||
* @name：EnableCustomSwagger2
|
||||
* @date：2024/9/29 10:01
|
||||
*/
|
||||
public @interface EnableCustomSwagger2 {
|
||||
}
|
||||
|
|
@ -0,0 +1,117 @@
|
|||
package com.muyu.common.swagger.config;
|
||||
|
||||
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
|
||||
import org.springframework.boot.context.properties.EnableConfigurationProperties;
|
||||
import org.springframework.context.annotation.Bean;
|
||||
import org.springframework.context.annotation.Configuration;
|
||||
import org.springframework.context.annotation.Import;
|
||||
import springfox.documentation.builders.ApiInfoBuilder;
|
||||
import springfox.documentation.builders.PathSelectors;
|
||||
import springfox.documentation.builders.RequestHandlerSelectors;
|
||||
import springfox.documentation.service.*;
|
||||
import springfox.documentation.spi.DocumentationType;
|
||||
import springfox.documentation.spi.service.contexts.SecurityContext;
|
||||
import springfox.documentation.spring.web.plugins.ApiSelectorBuilder;
|
||||
import springfox.documentation.spring.web.plugins.Docket;
|
||||
import springfox.documentation.swagger2.annotations.EnableSwagger2;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.Arrays;
|
||||
import java.util.List;
|
||||
import java.util.function.Predicate;
|
||||
|
||||
/**
|
||||
* @author 袁子龙
|
||||
* @package：com.muyu.common.swagger.config
|
||||
* @name：SwaggerAutoConfiguration
|
||||
* @date：2024/9/29 10:07
|
||||
*/
|
||||
@Configuration
|
||||
@EnableSwagger2
|
||||
@EnableConfigurationProperties(SwaggerProperties.class)
|
||||
@ConditionalOnProperty(name = "swagger.enabled", matchIfMissing = true)
|
||||
@Import({SwaggerBeanPostProcessor.class, SwaggerWebConfiguration.class})
|
||||
public class SwaggerAutoConfiguration {
|
||||
/**
|
||||
* 默认的排除路径，排除Spring Boot默认的错误处理路径和端点
|
||||
*/
|
||||
private static final List<String> DEFAULT_EXCLUDE_PATH = Arrays.asList("/error", "/actuator/**");
|
||||
|
||||
private static final String BASE_PATH = "/**";
|
||||
|
||||
@Bean
|
||||
public Docket api (SwaggerProperties swaggerProperties) {
|
||||
// base-path处理
|
||||
if (swaggerProperties.getBasePath().isEmpty()) {
|
||||
swaggerProperties.getBasePath().add(BASE_PATH);
|
||||
}
|
||||
// noinspection unchecked
|
||||
List<Predicate<String>> basePath = new ArrayList<Predicate<String>>();
|
||||
swaggerProperties.getBasePath().forEach(path -> basePath.add(PathSelectors.ant(path)));
|
||||
|
||||
// exclude-path处理
|
||||
if (swaggerProperties.getExcludePath().isEmpty()) {
|
||||
swaggerProperties.getExcludePath().addAll(DEFAULT_EXCLUDE_PATH);
|
||||
}
|
||||
|
||||
List<Predicate<String>> excludePath = new ArrayList<>();
|
||||
swaggerProperties.getExcludePath().forEach(path -> excludePath.add(PathSelectors.ant(path)));
|
||||
|
||||
ApiSelectorBuilder builder = new Docket(DocumentationType.SWAGGER_2).host(swaggerProperties.getHost())
|
||||
.apiInfo(apiInfo(swaggerProperties)).select()
|
||||
.apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()));
|
||||
|
||||
swaggerProperties.getBasePath().forEach(p -> builder.paths(PathSelectors.ant(p)));
|
||||
swaggerProperties.getExcludePath().forEach(p -> builder.paths(PathSelectors.ant(p).negate()));
|
||||
|
||||
return builder.build().securitySchemes(securitySchemes()).securityContexts(securityContexts()).pathMapping("/");
|
||||
}
|
||||
|
||||
/**
|
||||
* 安全模式，这里指定token通过Authorization头请求头传递
|
||||
*/
|
||||
private List<SecurityScheme> securitySchemes () {
|
||||
List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
|
||||
apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
|
||||
return apiKeyList;
|
||||
}
|
||||
|
||||
/**
|
||||
* 安全上下文
|
||||
*/
|
||||
private List<SecurityContext> securityContexts () {
|
||||
List<SecurityContext> securityContexts = new ArrayList<>();
|
||||
securityContexts.add(
|
||||
SecurityContext.builder()
|
||||
.securityReferences(defaultAuth())
|
||||
.operationSelector(o -> o.requestMappingPattern().matches("/.*"))
|
||||
.build());
|
||||
return securityContexts;
|
||||
}
|
||||
|
||||
/**
|
||||
* 默认的全局鉴权策略
|
||||
*
|
||||
* @return
|
||||
*/
|
||||
private List<SecurityReference> defaultAuth () {
|
||||
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
|
||||
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
|
||||
authorizationScopes[0] = authorizationScope;
|
||||
List<SecurityReference> securityReferences = new ArrayList<>();
|
||||
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
|
||||
return securityReferences;
|
||||
}
|
||||
|
||||
private ApiInfo apiInfo (SwaggerProperties swaggerProperties) {
|
||||
return new ApiInfoBuilder()
|
||||
.title(swaggerProperties.getTitle())
|
||||
.description(swaggerProperties.getDescription())
|
||||
.license(swaggerProperties.getLicense())
|
||||
.licenseUrl(swaggerProperties.getLicenseUrl())
|
||||
.termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
|
||||
.contact(new Contact(swaggerProperties.getContact().getName(), swaggerProperties.getContact().getUrl(), swaggerProperties.getContact().getEmail()))
|
||||
.version(swaggerProperties.getVersion())
|
||||
.build();
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
package com.muyu.common.swagger.config;
|
||||
|
||||
import org.springframework.beans.BeansException;
|
||||
import org.springframework.beans.factory.config.BeanPostProcessor;
|
||||
import org.springframework.util.ReflectionUtils;
|
||||
import org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping;
|
||||
import springfox.documentation.spring.web.plugins.WebFluxRequestHandlerProvider;
|
||||
import springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider;
|
||||
|
||||
import java.lang.reflect.Field;
|
||||
import java.util.List;
|
||||
import java.util.stream.Collectors;
|
||||
|
||||
/**
|
||||
* @author 袁子龙
|
||||
* @package：com.muyu.common.swagger.config
|
||||
* @name：SwaggerBeanPostProcessor
|
||||
* @date：2024/9/29 10:07
|
||||
*/
|
||||
public class SwaggerBeanPostProcessor implements BeanPostProcessor {
|
||||
@Override
|
||||
public Object postProcessAfterInitialization (Object bean, String beanName) throws BeansException {
|
||||
if (bean instanceof WebMvcRequestHandlerProvider || bean instanceof WebFluxRequestHandlerProvider) {
|
||||
customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
|
||||
}
|
||||
return bean;
|
||||
}
|
||||
|
||||
private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings (List<T> mappings) {
|
||||
List<T> copy = mappings.stream().filter(mapping -> mapping.getPatternParser() == null)
|
||||
.collect(Collectors.toList());
|
||||
mappings.clear();
|
||||
mappings.addAll(copy);
|
||||
}
|
||||
|
||||
@SuppressWarnings("unchecked")
|
||||
private List<RequestMappingInfoHandlerMapping> getHandlerMappings (Object bean) {
|
||||
try {
|
||||
Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
|
||||
field.setAccessible(true);
|
||||
return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
|
||||
} catch (IllegalArgumentException | IllegalAccessException e) {
|
||||
throw new IllegalStateException(e);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,303 @@
|
|||
package com.muyu.common.swagger.config;
|
||||
|
||||
import org.springframework.boot.context.properties.ConfigurationProperties;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* @author 袁子龙
|
||||
* @package：com.muyu.common.swagger.config
|
||||
* @name：SwaggerProperties
|
||||
* @date：2024/9/29 10:08
|
||||
*/
|
||||
@ConfigurationProperties("swagger")
|
||||
public class SwaggerProperties {
|
||||
/**
|
||||
* 是否开启swagger
|
||||
*/
|
||||
private Boolean enabled;
|
||||
|
||||
/**
|
||||
* swagger会解析的包路径
|
||||
**/
|
||||
private String basePackage = "";
|
||||
|
||||
/**
|
||||
* swagger会解析的url规则
|
||||
**/
|
||||
private List<String> basePath = new ArrayList<>();
|
||||
|
||||
/**
|
||||
* 在basePath基础上需要排除的url规则
|
||||
**/
|
||||
private List<String> excludePath = new ArrayList<>();
|
||||
|
||||
/**
|
||||
* 标题
|
||||
**/
|
||||
private String title = "";
|
||||
|
||||
/**
|
||||
* 描述
|
||||
**/
|
||||
private String description = "";
|
||||
|
||||
/**
|
||||
* 版本
|
||||
**/
|
||||
private String version = "";
|
||||
|
||||
/**
|
||||
* 许可证
|
||||
**/
|
||||
private String license = "";
|
||||
|
||||
/**
|
||||
* 许可证URL
|
||||
**/
|
||||
private String licenseUrl = "";
|
||||
|
||||
/**
|
||||
* 服务条款URL
|
||||
**/
|
||||
private String termsOfServiceUrl = "";
|
||||
|
||||
/**
|
||||
* host信息
|
||||
**/
|
||||
private String host = "";
|
||||
|
||||
/**
|
||||
* 联系人信息
|
||||
*/
|
||||
private Contact contact = new Contact();
|
||||
|
||||
/**
|
||||
* 全局统一鉴权配置
|
||||
**/
|
||||
private Authorization authorization = new Authorization();
|
||||
|
||||
public Boolean getEnabled () {
|
||||
return enabled;
|
||||
}
|
||||
|
||||
public void setEnabled (Boolean enabled) {
|
||||
this.enabled = enabled;
|
||||
}
|
||||
|
||||
public String getBasePackage () {
|
||||
return basePackage;
|
||||
}
|
||||
|
||||
public void setBasePackage (String basePackage) {
|
||||
this.basePackage = basePackage;
|
||||
}
|
||||
|
||||
public List<String> getBasePath () {
|
||||
return basePath;
|
||||
}
|
||||
|
||||
public void setBasePath (List<String> basePath) {
|
||||
this.basePath = basePath;
|
||||
}
|
||||
|
||||
public List<String> getExcludePath () {
|
||||
return excludePath;
|
||||
}
|
||||
|
||||
public void setExcludePath (List<String> excludePath) {
|
||||
this.excludePath = excludePath;
|
||||
}
|
||||
|
||||
public String getTitle () {
|
||||
return title;
|
||||
}
|
||||
|
||||
public void setTitle (String title) {
|
||||
this.title = title;
|
||||
}
|
||||
|
||||
public String getDescription () {
|
||||
return description;
|
||||
}
|
||||
|
||||
public void setDescription (String description) {
|
||||
this.description = description;
|
||||
}
|
||||
|
||||
public String getVersion () {
|
||||
return version;
|
||||
}
|
||||
|
||||
public void setVersion (String version) {
|
||||
this.version = version;
|
||||
}
|
||||
|
||||
public String getLicense () {
|
||||
return license;
|
||||
}
|
||||
|
||||
public void setLicense (String license) {
|
||||
this.license = license;
|
||||
}
|
||||
|
||||
public String getLicenseUrl () {
|
||||
return licenseUrl;
|
||||
}
|
||||
|
||||
public void setLicenseUrl (String licenseUrl) {
|
||||
this.licenseUrl = licenseUrl;
|
||||
}
|
||||
|
||||
public String getTermsOfServiceUrl () {
|
||||
return termsOfServiceUrl;
|
||||
}
|
||||
|
||||
public void setTermsOfServiceUrl (String termsOfServiceUrl) {
|
||||
this.termsOfServiceUrl = termsOfServiceUrl;
|
||||
}
|
||||
|
||||
public String getHost () {
|
||||
return host;
|
||||
}
|
||||
|
||||
public void setHost (String host) {
|
||||
this.host = host;
|
||||
}
|
||||
|
||||
public Contact getContact () {
|
||||
return contact;
|
||||
}
|
||||
|
||||
public void setContact (Contact contact) {
|
||||
this.contact = contact;
|
||||
}
|
||||
|
||||
public Authorization getAuthorization () {
|
||||
return authorization;
|
||||
}
|
||||
|
||||
public void setAuthorization (Authorization authorization) {
|
||||
this.authorization = authorization;
|
||||
}
|
||||
|
||||
public static class Contact {
|
||||
/**
|
||||
* 联系人
|
||||
**/
|
||||
private String name = "";
|
||||
/**
|
||||
* 联系人url
|
||||
**/
|
||||
private String url = "";
|
||||
/**
|
||||
* 联系人email
|
||||
**/
|
||||
private String email = "";
|
||||
|
||||
public String getName () {
|
||||
return name;
|
||||
}
|
||||
|
||||
public void setName (String name) {
|
||||
this.name = name;
|
||||
}
|
||||
|
||||
public String getUrl () {
|
||||
return url;
|
||||
}
|
||||
|
||||
public void setUrl (String url) {
|
||||
this.url = url;
|
||||
}
|
||||
|
||||
public String getEmail () {
|
||||
return email;
|
||||
}
|
||||
|
||||
public void setEmail (String email) {
|
||||
this.email = email;
|
||||
}
|
||||
}
|
||||
|
||||
public static class Authorization {
|
||||
/**
|
||||
* 鉴权策略ID，需要和SecurityReferences ID保持一致
|
||||
*/
|
||||
private String name = "";
|
||||
|
||||
/**
|
||||
* 需要开启鉴权URL的正则
|
||||
*/
|
||||
private String authRegex = "^.*$";
|
||||
|
||||
/**
|
||||
* 鉴权作用域列表
|
||||
*/
|
||||
private List<AuthorizationScope> authorizationScopeList = new ArrayList<>();
|
||||
|
||||
private List<String> tokenUrlList = new ArrayList<>();
|
||||
|
||||
public String getName () {
|
||||
return name;
|
||||
}
|
||||
|
||||
public void setName (String name) {
|
||||
this.name = name;
|
||||
}
|
||||
|
||||
public String getAuthRegex () {
|
||||
return authRegex;
|
||||
}
|
||||
|
||||
public void setAuthRegex (String authRegex) {
|
||||
this.authRegex = authRegex;
|
||||
}
|
||||
|
||||
public List<AuthorizationScope> getAuthorizationScopeList () {
|
||||
return authorizationScopeList;
|
||||
}
|
||||
|
||||
public void setAuthorizationScopeList (List<AuthorizationScope> authorizationScopeList) {
|
||||
this.authorizationScopeList = authorizationScopeList;
|
||||
}
|
||||
|
||||
public List<String> getTokenUrlList () {
|
||||
return tokenUrlList;
|
||||
}
|
||||
|
||||
public void setTokenUrlList (List<String> tokenUrlList) {
|
||||
this.tokenUrlList = tokenUrlList;
|
||||
}
|
||||
}
|
||||
|
||||
public static class AuthorizationScope {
|
||||
/**
|
||||
* 作用域名称
|
||||
*/
|
||||
private String scope = "";
|
||||
|
||||
/**
|
||||
* 作用域描述
|
||||
*/
|
||||
private String description = "";
|
||||
|
||||
public String getScope () {
|
||||
return scope;
|
||||
}
|
||||
|
||||
public void setScope (String scope) {
|
||||
this.scope = scope;
|
||||
}
|
||||
|
||||
public String getDescription () {
|
||||
return description;
|
||||
}
|
||||
|
||||
public void setDescription (String description) {
|
||||
this.description = description;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
package com.muyu.common.swagger.config;
|
||||
|
||||
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
|
||||
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
|
||||
|
||||
/**
|
||||
* @author 袁子龙
|
||||
* @package：com.muyu.common.swagger.config
|
||||
* @name：SwaggerWebConfiguration
|
||||
* @date：2024/9/29 10:08
|
||||
*/
|
||||
public class SwaggerWebConfiguration implements WebMvcConfigurer {
|
||||
@Override
|
||||
public void addResourceHandlers (ResourceHandlerRegistry registry) {
|
||||
/** swagger-ui 地址 */
|
||||
registry.addResourceHandler("/swagger-ui/**")
|
||||
.addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
|
||||
}
|
||||
}
|
||||
|
|
@ -21,6 +21,7 @@
|
|||
<module>cloud-common-xxl</module>
|
||||
<module>cloud-common-rabbit</module>
|
||||
<module>cloud-common-saas</module>
|
||||
<module>cloud-common-swagger</module>
|
||||
</modules>
|
||||
|
||||
<artifactId>cloud-common</artifactId>
|
||||
|
|
|
|||
Loading…
Reference in New Issue