mirror of
https://gitee.com/dromara/RuoYi-Cloud-Plus.git
synced 2025-09-06 20:38:35 +00:00
add 新增 ruoyi-doc 模块 集成 Knife4j
This commit is contained in:
yueye
@@ -17,17 +17,22 @@
|
||||
|
||||
<dependencies>
|
||||
|
||||
<!-- SpringBoot core -->
|
||||
<dependency>
|
||||
<groupId>com.ruoyi</groupId>
|
||||
<artifactId>ruoyi-common-core</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- SpringBoot Web -->
|
||||
<dependency>
|
||||
<groupId>com.ruoyi</groupId>
|
||||
<artifactId>ruoyi-common-web</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- Swagger -->
|
||||
<!-- knife4j -->
|
||||
<dependency>
|
||||
<groupId>io.springfox</groupId>
|
||||
<artifactId>springfox-swagger2</artifactId>
|
||||
<version>${swagger.fox.version}</version>
|
||||
<groupId>com.github.xiaoymin</groupId>
|
||||
<artifactId>knife4j-micro-spring-boot-starter</artifactId>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
|
||||
@@ -1,15 +0,0 @@
|
||||
package com.ruoyi.common.swagger.annotation;
|
||||
|
||||
import com.ruoyi.common.swagger.config.SwaggerAutoConfiguration;
|
||||
import org.springframework.context.annotation.Import;
|
||||
|
||||
import java.lang.annotation.*;
|
||||
|
||||
@Target({ElementType.TYPE})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@Documented
|
||||
@Inherited
|
||||
@Import({SwaggerAutoConfiguration.class})
|
||||
public @interface EnableCustomSwagger2 {
|
||||
|
||||
}
|
||||
@@ -1,116 +1,119 @@
|
||||
package com.ruoyi.common.swagger.config;
|
||||
|
||||
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
|
||||
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
|
||||
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
|
||||
import org.springframework.context.annotation.Bean;
|
||||
import org.springframework.context.annotation.Configuration;
|
||||
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;
|
||||
|
||||
@Configuration
|
||||
@EnableSwagger2
|
||||
@EnableAutoConfiguration
|
||||
@ConditionalOnProperty(name = "swagger.enabled", matchIfMissing = true)
|
||||
public class SwaggerAutoConfiguration {
|
||||
/**
|
||||
* 默认的排除路径，排除Spring Boot默认的错误处理路径和端点
|
||||
*/
|
||||
private static final List<String> DEFAULT_EXCLUDE_PATH = Arrays.asList("/error", "/actuator/**");
|
||||
|
||||
private static final String BASE_PATH = "/**";
|
||||
|
||||
@Bean
|
||||
@ConditionalOnMissingBean
|
||||
public SwaggerProperties swaggerProperties() {
|
||||
return new SwaggerProperties();
|
||||
}
|
||||
|
||||
@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();
|
||||
}
|
||||
}
|
||||
package com.ruoyi.common.swagger.config;
|
||||
|
||||
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
|
||||
import com.ruoyi.common.swagger.config.properties.SwaggerProperties;
|
||||
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 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 java.util.ArrayList;
|
||||
import java.util.Arrays;
|
||||
import java.util.List;
|
||||
import java.util.function.Predicate;
|
||||
|
||||
/**
|
||||
* Swagger 文档配置
|
||||
*
|
||||
* @author Lion Li
|
||||
*/
|
||||
@Configuration
|
||||
@EnableKnife4j
|
||||
@EnableConfigurationProperties(SwaggerProperties.class)
|
||||
@ConditionalOnProperty(name = "swagger.enabled", matchIfMissing = true)
|
||||
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<>();
|
||||
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.OAS_30)
|
||||
.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<>();
|
||||
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;
|
||||
}
|
||||
|
||||
/**
|
||||
* 默认的全局鉴权策略
|
||||
*/
|
||||
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();
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,20 +0,0 @@
|
||||
package com.ruoyi.common.swagger.config;
|
||||
|
||||
import org.springframework.context.annotation.Configuration;
|
||||
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
|
||||
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
|
||||
|
||||
/**
|
||||
* swagger 资源映射路径
|
||||
*
|
||||
* @author ruoyi
|
||||
*/
|
||||
@Configuration
|
||||
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/");
|
||||
}
|
||||
}
|
||||
@@ -1,140 +1,146 @@
|
||||
package com.ruoyi.common.swagger.config;
|
||||
|
||||
import lombok.Data;
|
||||
import lombok.NoArgsConstructor;
|
||||
import lombok.experimental.Accessors;
|
||||
import org.springframework.boot.context.properties.ConfigurationProperties;
|
||||
import org.springframework.stereotype.Component;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@Accessors(chain = true)
|
||||
@Component
|
||||
@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();
|
||||
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@Accessors(chain = true)
|
||||
public static class Contact {
|
||||
/**
|
||||
* 联系人
|
||||
**/
|
||||
private String name = "";
|
||||
/**
|
||||
* 联系人url
|
||||
**/
|
||||
private String url = "";
|
||||
/**
|
||||
* 联系人email
|
||||
**/
|
||||
private String email = "";
|
||||
|
||||
}
|
||||
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@Accessors(chain = true)
|
||||
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<>();
|
||||
|
||||
}
|
||||
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@Accessors(chain = true)
|
||||
public static class AuthorizationScope {
|
||||
/**
|
||||
* 作用域名称
|
||||
*/
|
||||
private String scope = "";
|
||||
|
||||
/**
|
||||
* 作用域描述
|
||||
*/
|
||||
private String description = "";
|
||||
|
||||
}
|
||||
}
|
||||
package com.ruoyi.common.swagger.config.properties;
|
||||
|
||||
import lombok.Data;
|
||||
import lombok.NoArgsConstructor;
|
||||
import lombok.experimental.Accessors;
|
||||
import org.springframework.boot.context.properties.ConfigurationProperties;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* swagger 配置属性
|
||||
*
|
||||
* @author Lion Li
|
||||
*/
|
||||
@Data
|
||||
@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();
|
||||
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@Accessors(chain = true)
|
||||
public static class Contact {
|
||||
|
||||
/**
|
||||
* 联系人
|
||||
**/
|
||||
private String name = "";
|
||||
/**
|
||||
* 联系人url
|
||||
**/
|
||||
private String url = "";
|
||||
/**
|
||||
* 联系人email
|
||||
**/
|
||||
private String email = "";
|
||||
|
||||
}
|
||||
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@Accessors(chain = true)
|
||||
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<>();
|
||||
|
||||
}
|
||||
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@Accessors(chain = true)
|
||||
public static class AuthorizationScope {
|
||||
|
||||
/**
|
||||
* 作用域名称
|
||||
*/
|
||||
private String scope = "";
|
||||
|
||||
/**
|
||||
* 作用域描述
|
||||
*/
|
||||
private String description = "";
|
||||
|
||||
}
|
||||
|
||||
}
|
||||
@@ -1,3 +1,2 @@
|
||||
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
|
||||
com.ruoyi.common.swagger.config.SwaggerAutoConfiguration,\
|
||||
com.ruoyi.common.swagger.config.SwaggerWebConfiguration
|
||||
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
|
||||
com.ruoyi.common.swagger.config.SwaggerAutoConfiguration
|
||||
|
||||
Reference in New Issue
Block a user