| | |
|---|
| | | package com.ruoyi.framework.config; |
|---|
| | | |
|---|
| | | import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j; |
|---|
| | | import com.ruoyi.common.utils.StringUtils; |
|---|
| | | import com.ruoyi.framework.config.properties.SwaggerProperties; |
|---|
| | | import io.swagger.annotations.ApiOperation; |
|---|
| | | import org.springframework.beans.factory.annotation.Autowired; |
|---|
| | | import com.ruoyi.framework.handler.OpenApiHandler; |
|---|
| | | import io.swagger.v3.oas.models.OpenAPI; |
|---|
| | | import io.swagger.v3.oas.models.Paths; |
|---|
| | | import io.swagger.v3.oas.models.info.Info; |
|---|
| | | import io.swagger.v3.oas.models.security.SecurityRequirement; |
|---|
| | | import lombok.RequiredArgsConstructor; |
|---|
| | | import org.springdoc.core.*; |
|---|
| | | import org.springdoc.core.customizers.OpenApiBuilderCustomizer; |
|---|
| | | import org.springdoc.core.customizers.OpenApiCustomiser; |
|---|
| | | import org.springdoc.core.customizers.ServerBaseUrlCustomizer; |
|---|
| | | import org.springdoc.core.providers.JavadocProvider; |
|---|
| | | import org.springframework.boot.autoconfigure.AutoConfigureBefore; |
|---|
| | | import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; |
|---|
| | | import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; |
|---|
| | | import org.springframework.boot.autoconfigure.web.ServerProperties; |
|---|
| | | 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.Docket; |
|---|
| | | import springfox.documentation.swagger2.annotations.EnableSwagger2; |
|---|
| | | |
|---|
| | | import java.util.ArrayList; |
|---|
| | | import java.util.List; |
|---|
| | | import java.util.Optional; |
|---|
| | | import java.util.Set; |
|---|
| | | |
|---|
| | | /** |
|---|
| | | * Swagger2的接口配置 |
|---|
| | | * Swagger 文档配置 |
|---|
| | | * |
|---|
| | | * @author Lion Li |
|---|
| | | */ |
|---|
| | | @RequiredArgsConstructor |
|---|
| | | @Configuration |
|---|
| | | @EnableSwagger2 |
|---|
| | | @EnableKnife4j |
|---|
| | | @AutoConfigureBefore(SpringDocConfiguration.class) |
|---|
| | | @ConditionalOnProperty(name = "swagger.enabled", havingValue = "true", matchIfMissing = true) |
|---|
| | | public class SwaggerConfig { |
|---|
| | | |
|---|
| | | @Autowired |
|---|
| | | private SwaggerProperties swaggerProperties; |
|---|
| | | private final SwaggerProperties swaggerProperties; |
|---|
| | | private final ServerProperties serverProperties; |
|---|
| | | |
|---|
| | | /** |
|---|
| | | * 创建API |
|---|
| | | */ |
|---|
| | | @Bean |
|---|
| | | public Docket createRestApi() { |
|---|
| | | return new Docket(DocumentationType.SWAGGER_2) |
|---|
| | | .enable(swaggerProperties.getEnabled()) |
|---|
| | | // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息） |
|---|
| | | .apiInfo(apiInfo()) |
|---|
| | | // 设置哪些接口暴露给Swagger展示 |
|---|
| | | .select() |
|---|
| | | // 扫描所有有注解的api，用这种方式更灵活 |
|---|
| | | .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) |
|---|
| | | // 扫描指定包中的swagger注解 |
|---|
| | | // .apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.tool.swagger")) |
|---|
| | | // 扫描所有 .apis(RequestHandlerSelectors.any()) |
|---|
| | | .paths(PathSelectors.any()) |
|---|
| | | .build() |
|---|
| | | /* 设置安全模式，swagger可以设置访问token */ |
|---|
| | | .securitySchemes(securitySchemes()) |
|---|
| | | .securityContexts(securityContexts()) |
|---|
| | | .pathMapping(swaggerProperties.getPathMapping()); |
|---|
| | | } |
|---|
| | | @Bean |
|---|
| | | @ConditionalOnMissingBean(OpenAPI.class) |
|---|
| | | public OpenAPI openApi() { |
|---|
| | | OpenAPI openApi = new OpenAPI(); |
|---|
| | | // 文档基本信息 |
|---|
| | | SwaggerProperties.InfoProperties infoProperties = swaggerProperties.getInfo(); |
|---|
| | | Info info = convertInfo(infoProperties); |
|---|
| | | openApi.info(info); |
|---|
| | | // 扩展文档信息 |
|---|
| | | openApi.externalDocs(swaggerProperties.getExternalDocs()); |
|---|
| | | openApi.tags(swaggerProperties.getTags()); |
|---|
| | | openApi.paths(swaggerProperties.getPaths()); |
|---|
| | | openApi.components(swaggerProperties.getComponents()); |
|---|
| | | Set<String> keySet = swaggerProperties.getComponents().getSecuritySchemes().keySet(); |
|---|
| | | List<SecurityRequirement> list = new ArrayList<>(); |
|---|
| | | SecurityRequirement securityRequirement = new SecurityRequirement(); |
|---|
| | | keySet.forEach(securityRequirement::addList); |
|---|
| | | list.add(securityRequirement); |
|---|
| | | openApi.security(list); |
|---|
| | | |
|---|
| | | /** |
|---|
| | | * 安全模式，这里指定token通过Authorization头请求头传递 |
|---|
| | | */ |
|---|
| | | private List<SecurityScheme> securitySchemes() { |
|---|
| | | List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>(); |
|---|
| | | apiKeyList.add(new ApiKey("Authorization", "Authorization", "header")); |
|---|
| | | return apiKeyList; |
|---|
| | | } |
|---|
| | | return openApi; |
|---|
| | | } |
|---|
| | | |
|---|
| | | /** |
|---|
| | | * 安全上下文 |
|---|
| | | */ |
|---|
| | | private List<SecurityContext> securityContexts() { |
|---|
| | | List<SecurityContext> securityContexts = new ArrayList<>(); |
|---|
| | | securityContexts.add( |
|---|
| | | SecurityContext.builder() |
|---|
| | | .securityReferences(defaultAuth()) |
|---|
| | | .forPaths(PathSelectors.regex("^(?!auth).*$")) |
|---|
| | | .build()); |
|---|
| | | return securityContexts; |
|---|
| | | } |
|---|
| | | private Info convertInfo(SwaggerProperties.InfoProperties infoProperties) { |
|---|
| | | Info info = new Info(); |
|---|
| | | info.setTitle(infoProperties.getTitle()); |
|---|
| | | info.setDescription(infoProperties.getDescription()); |
|---|
| | | info.setContact(infoProperties.getContact()); |
|---|
| | | info.setLicense(infoProperties.getLicense()); |
|---|
| | | info.setVersion(infoProperties.getVersion()); |
|---|
| | | return info; |
|---|
| | | } |
|---|
| | | |
|---|
| | | /** |
|---|
| | | * 默认的安全上引用 |
|---|
| | | */ |
|---|
| | | 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; |
|---|
| | | } |
|---|
| | | /** |
|---|
| | | * 自定义 openapi 处理器 |
|---|
| | | */ |
|---|
| | | @Bean |
|---|
| | | public OpenAPIService openApiBuilder(Optional<OpenAPI> openAPI, |
|---|
| | | SecurityService securityParser, |
|---|
| | | SpringDocConfigProperties springDocConfigProperties, PropertyResolverUtils propertyResolverUtils, |
|---|
| | | Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomisers, |
|---|
| | | Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomisers, Optional<JavadocProvider> javadocProvider) { |
|---|
| | | return new OpenApiHandler(openAPI, securityParser, springDocConfigProperties, propertyResolverUtils, openApiBuilderCustomisers, serverBaseUrlCustomisers, javadocProvider); |
|---|
| | | } |
|---|
| | | |
|---|
| | | /** |
|---|
| | | * 添加摘要信息 |
|---|
| | | */ |
|---|
| | | private ApiInfo apiInfo() { |
|---|
| | | // 用ApiInfoBuilder进行定制 |
|---|
| | | SwaggerProperties.Contact contact = swaggerProperties.getContact(); |
|---|
| | | return new ApiInfoBuilder() |
|---|
| | | // 设置标题 |
|---|
| | | .title(swaggerProperties.getTitle()) |
|---|
| | | // 描述 |
|---|
| | | .description(swaggerProperties.getDescription()) |
|---|
| | | // 作者信息 |
|---|
| | | .contact(new Contact(contact.getName(), contact.getUrl(), contact.getEmail())) |
|---|
| | | // 版本 |
|---|
| | | .version(swaggerProperties.getVersion()) |
|---|
| | | .build(); |
|---|
| | | } |
|---|
| | | /** |
|---|
| | | * 对已经生成好的 OpenApi 进行自定义操作 |
|---|
| | | */ |
|---|
| | | @Bean |
|---|
| | | public OpenApiCustomiser openApiCustomiser() { |
|---|
| | | String contextPath = serverProperties.getServlet().getContextPath(); |
|---|
| | | String finalContextPath; |
|---|
| | | if (StringUtils.isBlank(contextPath) || "/".equals(contextPath)) { |
|---|
| | | finalContextPath = ""; |
|---|
| | | } else { |
|---|
| | | finalContextPath = contextPath; |
|---|
| | | } |
|---|
| | | // 对所有路径增加前置上下文路径 |
|---|
| | | return openApi -> { |
|---|
| | | Paths oldPaths = openApi.getPaths(); |
|---|
| | | if (oldPaths instanceof PlusPaths) { |
|---|
| | | return; |
|---|
| | | } |
|---|
| | | PlusPaths newPaths = new PlusPaths(); |
|---|
| | | oldPaths.forEach((k,v) -> newPaths.addPathItem(finalContextPath + k, v)); |
|---|
| | | openApi.setPaths(newPaths); |
|---|
| | | }; |
|---|
| | | } |
|---|
| | | |
|---|
| | | /** |
|---|
| | | * 单独使用一个类便于判断 解决springdoc路径拼接重复问题 |
|---|
| | | * |
|---|
| | | * @author Lion Li |
|---|
| | | */ |
|---|
| | | static class PlusPaths extends Paths { |
|---|
| | | |
|---|
| | | public PlusPaths() { |
|---|
| | | super(); |
|---|
| | | } |
|---|
| | | } |
|---|
| | | |
|---|
| | | } |
|---|
