BJ_ZTEITS-Developers / parking-cloud-yudao

Commit 711a39b8e9b2fda99c8cf972b9143989bcf5f915

Authored by YunaiV
1 parent ba65a864

spring doc：增加模块分组

Inline Side-by-side
Showing 17 changed files with 262 additions and 68 deletions
yudao-framework/yudao-spring-boot-starter-web/src/main/java/cn/iocoder/yudao/framework/swagger/config/YudaoSwaggerAutoConfiguration.java
  View file @711a39b
@@ -6,6 +6,7 @@ import io.swagger.v3.oas.models.info.Contact; @@ -6,6 +6,7 @@ import io.swagger.v3.oas.models.info.Contact;
6 import io.swagger.v3.oas.models.info.Info; 6 import io.swagger.v3.oas.models.info.Info;
7 import io.swagger.v3.oas.models.info.License; 7 import io.swagger.v3.oas.models.info.License;
8 import io.swagger.v3.oas.models.media.IntegerSchema; 8 import io.swagger.v3.oas.models.media.IntegerSchema;
  9 +import io.swagger.v3.oas.models.media.StringSchema;
9 import io.swagger.v3.oas.models.parameters.Parameter; 10 import io.swagger.v3.oas.models.parameters.Parameter;
10 import io.swagger.v3.oas.models.security.SecurityRequirement; 11 import io.swagger.v3.oas.models.security.SecurityRequirement;
11 import io.swagger.v3.oas.models.security.SecurityScheme; 12 import io.swagger.v3.oas.models.security.SecurityScheme;
@@ -27,8 +28,11 @@ import java.util.Optional; @@ -27,8 +28,11 @@ import java.util.Optional;
27 import static cn.iocoder.yudao.framework.web.core.util.WebFrameworkUtils.HEADER_TENANT_ID; 28 import static cn.iocoder.yudao.framework.web.core.util.WebFrameworkUtils.HEADER_TENANT_ID;
28 29
29 /** 30 /**
30 - * springdoc 自动配置类  
31 - * 使用 knife4j.enable=false 禁用 Swagger 31 + * Swagger 自动配置类，基于 OpenAPI + Springdoc 实现。
  32 + *
  33 + * 友情提示：
  34 + * 1. Springdoc 文档地址：<a href="https://github.com/springdoc/springdoc-openapi">仓库</a>
  35 + * 2. Swagger 规范，于 2015 更名为 OpenAPI 规范，本质是一个东西
32 * 36 *
33 * @author 芋道源码 37 * @author 芋道源码
34 */ 38 */
@@ -37,95 +41,112 @@ import static cn.iocoder.yudao.framework.web.core.util.WebFrameworkUtils.HEADER_ @@ -37,95 +41,112 @@ import static cn.iocoder.yudao.framework.web.core.util.WebFrameworkUtils.HEADER_
37 @EnableConfigurationProperties(SwaggerProperties.class) 41 @EnableConfigurationProperties(SwaggerProperties.class)
38 public class YudaoSwaggerAutoConfiguration { 42 public class YudaoSwaggerAutoConfiguration {
39 43
  44 + // ========== 全局 OpenAPI 配置 ==========
  45 +
40 @Bean 46 @Bean
41 public OpenAPI createApi(SwaggerProperties properties) { 47 public OpenAPI createApi(SwaggerProperties properties) {
42 - Map<String, SecurityScheme> maps = securityScheme(); 48 + Map<String, SecurityScheme> securitySchemas = buildSecuritySchemes();
43 OpenAPI openAPI = new OpenAPI() 49 OpenAPI openAPI = new OpenAPI()
  50 + // 接口信息
44 .info(buildInfo(properties)) 51 .info(buildInfo(properties))
45 - .components(new Components().securitySchemes(maps)) 52 + // 接口安全配置
  53 + .components(new Components().securitySchemes(securitySchemas))
46 .addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION)); 54 .addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION));
47 - maps.keySet().forEach(key -> openAPI.addSecurityItem(new SecurityRequirement().addList(key))); 55 + securitySchemas.keySet().forEach(key -> openAPI.addSecurityItem(new SecurityRequirement().addList(key)));
48 return openAPI; 56 return openAPI;
49 } 57 }
50 58
51 /** 59 /**
52 - * 自定义 openapi 处理器 60 + * API 摘要信息
  61 + */
  62 + private Info buildInfo(SwaggerProperties properties) {
  63 + return new Info()
  64 + .title(properties.getTitle())
  65 + .description(properties.getDescription())
  66 + .version(properties.getVersion())
  67 + .contact(new Contact().name(properties.getAuthor()).url(properties.getUrl()).email(properties.getEmail()))
  68 + .license(new License().name(properties.getLicense()).url(properties.getLicenseUrl()));
  69 + }
  70 +
  71 + /**
  72 + * 安全模式，这里配置通过请求头 Authorization 传递 token 参数
  73 + */
  74 + private Map<String, SecurityScheme> buildSecuritySchemes() {
  75 + Map<String, SecurityScheme> securitySchemes = new HashMap<>();
  76 + SecurityScheme securityScheme = new SecurityScheme()
  77 + .type(SecurityScheme.Type.APIKEY) // 类型
  78 + .name(HttpHeaders.AUTHORIZATION) // 请求头的 name
  79 + .in(SecurityScheme.In.HEADER); // token 所在位置
  80 + securitySchemes.put(HttpHeaders.AUTHORIZATION, securityScheme);
  81 + return securitySchemes;
  82 + }
  83 +
  84 + /**
  85 + * 自定义 OpenAPI 处理器
53 */ 86 */
54 @Bean 87 @Bean
55 public OpenAPIService openApiBuilder(Optional<OpenAPI> openAPI, 88 public OpenAPIService openApiBuilder(Optional<OpenAPI> openAPI,
56 SecurityService securityParser, 89 SecurityService securityParser,
57 SpringDocConfigProperties springDocConfigProperties, 90 SpringDocConfigProperties springDocConfigProperties,
58 PropertyResolverUtils propertyResolverUtils, 91 PropertyResolverUtils propertyResolverUtils,
59 - Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomisers,  
60 - Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomisers, 92 + Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomizers,
  93 + Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomizers,
61 Optional<JavadocProvider> javadocProvider) { 94 Optional<JavadocProvider> javadocProvider) {
62 - return new OpenAPIService(openAPI, securityParser, springDocConfigProperties, propertyResolverUtils, openApiBuilderCustomisers, serverBaseUrlCustomisers, javadocProvider); 95 +
  96 + return new OpenAPIService(openAPI, securityParser, springDocConfigProperties,
  97 + propertyResolverUtils, openApiBuilderCustomizers, serverBaseUrlCustomizers, javadocProvider);
63 } 98 }
64 99
  100 + // ========== 分组 OpenAPI 配置 ==========
  101 +
  102 + /**
  103 + * 所有模块的 API 分组
  104 + */
65 @Bean 105 @Bean
66 - public GroupedOpenApi appApi() {  
67 - return GroupedOpenApi.builder()  
68 - .group("app")  
69 - .addOperationCustomizer((operation, handlerMethod) ->  
70 - operation.addParametersItem(globalHeaderParameter())  
71 - )  
72 - .pathsToMatch("/app-api/**")  
73 - .build(); 106 + public GroupedOpenApi allGroupedOpenApi() {
  107 + return buildGroupedOpenApi("all", "");
74 } 108 }
75 109
76 - @Bean  
77 - public GroupedOpenApi adminApi() {  
78 - return GroupedOpenApi.builder()  
79 - .group("admin")  
80 - .addOperationCustomizer((operation, handlerMethod) ->  
81 - operation.addParametersItem(globalHeaderParameter())  
82 - )  
83 - .pathsToMatch("/admin-api/**")  
84 - .build(); 110 + public static GroupedOpenApi buildGroupedOpenApi(String group) {
  111 + return buildGroupedOpenApi(group, group);
85 } 112 }
86 113
87 - /**  
88 - * API 摘要信息  
89 - */  
90 - private Info buildInfo(SwaggerProperties properties) {  
91 - return new Info()  
92 - .title(properties.getTitle())  
93 - .description(properties.getDescription())  
94 - .version(properties.getVersion())  
95 - .contact(new Contact().name(properties.getAuthor()).url(properties.getUrl()).email(properties.getEmail()))  
96 - .license(new License().name(properties.getLicense()).url(properties.getLicenseUrl())); 114 + public static GroupedOpenApi buildGroupedOpenApi(String group, String path) {
  115 + return GroupedOpenApi.builder()
  116 + .group(group)
  117 + .pathsToMatch("/admin-api/" + path + "/**", "/app-api/" + path + "/**")
  118 + .addOperationCustomizer((operation, handlerMethod) -> operation
  119 + .addParametersItem(buildTenantHeaderParameter())
  120 + .addParametersItem(buildSecurityHeaderParameter()))
  121 + .build();
97 } 122 }
98 123
99 /** 124 /**
100 - * 安全模式，这里配置通过请求头 Authorization 传递 token 参数 125 + * 构建 Tenant 租户编号请求头参数
  126 + *
  127 + * @return 多租户参数
101 */ 128 */
102 - private Map<String, SecurityScheme> securityScheme() {  
103 - Map<String, SecurityScheme> map = new HashMap<>();  
104 - SecurityScheme securityScheme = new SecurityScheme()  
105 - //类型  
106 - .type(SecurityScheme.Type.APIKEY)  
107 - //请求头的name  
108 - .name(HttpHeaders.AUTHORIZATION)  
109 - //token所在未知  
110 - .in(SecurityScheme.In.HEADER);  
111 - map.put(HttpHeaders.AUTHORIZATION, securityScheme);  
112 - return map; 129 + private static Parameter buildTenantHeaderParameter() {
  130 + return new Parameter()
  131 + .name(HEADER_TENANT_ID) // header 名
  132 + .description("租户编号") // 描述
  133 + .in(String.valueOf(SecurityScheme.In.HEADER)) // 请求 header
  134 + .schema(new IntegerSchema()._default(1L).name(HEADER_TENANT_ID).description("租户编号")); // 默认：使用租户编号为 1
113 } 135 }
114 136
115 /** 137 /**
116 - * globalHeaderParameter  
117 - * @return 多租户参数 138 + * 构建 Authorization 认证请求头参数
  139 + *
  140 + * 解决 Knife4j <a href="https://gitee.com/xiaoym/knife4j/issues/I69QBU">Authorize 未生效，请求header里未包含参数</a>
  141 + *
  142 + * @return 认证参数
118 */ 143 */
119 - private static Parameter globalHeaderParameter() { 144 + private static Parameter buildSecurityHeaderParameter() {
120 return new Parameter() 145 return new Parameter()
121 - .name(HEADER_TENANT_ID)  
122 - .description("租户编号")  
123 - .in(String.valueOf(SecurityScheme.In.HEADER))  
124 - .schema(new IntegerSchema()  
125 - ._default(1L)  
126 - .name(HEADER_TENANT_ID)  
127 - .description("租户编号")  
128 - ); 146 + .name(HttpHeaders.AUTHORIZATION) // header 名
  147 + .description("认证 Token") // 描述
  148 + .in(String.valueOf(SecurityScheme.In.HEADER)) // 请求 header
  149 + .schema(new StringSchema()._default("Bearer test1").name(HEADER_TENANT_ID).description("认证 Token")); // 默认：使用用户编号为 1
129 } 150 }
130 151
131 } 152 }
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/framework/web/config/BpmWebConfiguration.java 0 → 100644
  View file @711a39b
  1 +package cn.iocoder.yudao.module.bpm.framework.web.config;
  2 +
  3 +import cn.iocoder.yudao.framework.swagger.config.YudaoSwaggerAutoConfiguration;
  4 +import org.springdoc.core.GroupedOpenApi;
  5 +import org.springframework.context.annotation.Bean;
  6 +import org.springframework.context.annotation.Configuration;
  7 +
  8 +/**
  9 + * bpm 模块的 web 组件的 Configuration
  10 + *
  11 + * @author 芋道源码
  12 + */
  13 +@Configuration(proxyBeanMethods = false)
  14 +public class BpmWebConfiguration {
  15 +
  16 + /**
  17 + * bpm 模块的 API 分组
  18 + */
  19 + @Bean
  20 + public GroupedOpenApi bpmGroupedOpenApi() {
  21 + return YudaoSwaggerAutoConfiguration.buildGroupedOpenApi("bpm");
  22 + }
  23 +
  24 +}
yudao-module-bpm/yudao-module-bpm-biz/src/main/java/cn/iocoder/yudao/module/bpm/framework/web/package-info.java 0 → 100644
  View file @711a39b
  1 +/**
  2 + * bpm 模块的 web 配置
  3 + */
  4 +package cn.iocoder.yudao.module.bpm.framework.web;
yudao-module-infra/yudao-module-infra-biz/src/main/java/cn/iocoder/yudao/module/infra/framework/web/config/InfraWebConfiguration.java 0 → 100644
  View file @711a39b
  1 +package cn.iocoder.yudao.module.infra.framework.web.config;
  2 +
  3 +import cn.iocoder.yudao.framework.swagger.config.YudaoSwaggerAutoConfiguration;
  4 +import org.springdoc.core.GroupedOpenApi;
  5 +import org.springframework.context.annotation.Bean;
  6 +import org.springframework.context.annotation.Configuration;
  7 +
  8 +/**
  9 + * infra 模块的 web 组件的 Configuration
  10 + *
  11 + * @author 芋道源码
  12 + */
  13 +@Configuration(proxyBeanMethods = false)
  14 +public class InfraWebConfiguration {
  15 +
  16 + /**
  17 + * infra 模块的 API 分组
  18 + */
  19 + @Bean
  20 + public GroupedOpenApi infraGroupedOpenApi() {
  21 + return YudaoSwaggerAutoConfiguration.buildGroupedOpenApi("infra");
  22 + }
  23 +
  24 +}
yudao-module-infra/yudao-module-infra-biz/src/main/java/cn/iocoder/yudao/module/infra/framework/web/package-info.java 0 → 100644
  View file @711a39b
  1 +/**
  2 + * infra 模块的 web 配置
  3 + */
  4 +package cn.iocoder.yudao.module.infra.framework.web;
yudao-module-mall/README.md 0 → 100644
  View file @711a39b
  1 +mall 后端的代码，暂时归档成一个 yudao-module-mall 的压缩包。
  2 +
  3 +精力有限，近期还是以管理后台的工作流、大屏报表等功能为主！
  4 +
yudao-module-mall/yudao-module-mall.zip 0 → 100755
View file @711a39b
No preview for this file type
yudao-module-member/yudao-module-member-biz/src/main/java/cn/iocoder/yudao/module/member/framework/web/config/MemberWebConfiguration.java 0 → 100644
  View file @711a39b
  1 +package cn.iocoder.yudao.module.member.framework.web.config;
  2 +
  3 +import cn.iocoder.yudao.framework.swagger.config.YudaoSwaggerAutoConfiguration;
  4 +import org.springdoc.core.GroupedOpenApi;
  5 +import org.springframework.context.annotation.Bean;
  6 +import org.springframework.context.annotation.Configuration;
  7 +
  8 +/**
  9 + * member 模块的 web 组件的 Configuration
  10 + *
  11 + * @author 芋道源码
  12 + */
  13 +@Configuration(proxyBeanMethods = false)
  14 +public class MemberWebConfiguration {
  15 +
  16 + /**
  17 + * member 模块的 API 分组
  18 + */
  19 + @Bean
  20 + public GroupedOpenApi memberGroupedOpenApi() {
  21 + return YudaoSwaggerAutoConfiguration.buildGroupedOpenApi("member");
  22 + }
  23 +
  24 +}
yudao-module-member/yudao-module-member-biz/src/main/java/cn/iocoder/yudao/module/member/framework/web/package-info.java 0 → 100644
  View file @711a39b
  1 +/**
  2 + * member 模块的 web 配置
  3 + */
  4 +package cn.iocoder.yudao.module.member.framework.web;
yudao-module-mp/yudao-module-mp-biz/src/main/java/cn/iocoder/yudao/module/mp/framework/web/config/MpWebConfiguration.java 0 → 100644
  View file @711a39b
  1 +package cn.iocoder.yudao.module.mp.framework.web.config;
  2 +
  3 +import cn.iocoder.yudao.framework.swagger.config.YudaoSwaggerAutoConfiguration;
  4 +import org.springdoc.core.GroupedOpenApi;
  5 +import org.springframework.context.annotation.Bean;
  6 +import org.springframework.context.annotation.Configuration;
  7 +
  8 +/**
  9 + * mp 模块的 web 组件的 Configuration
  10 + *
  11 + * @author 芋道源码
  12 + */
  13 +@Configuration(proxyBeanMethods = false)
  14 +public class MpWebConfiguration {
  15 +
  16 + /**
  17 + * mp 模块的 API 分组
  18 + */
  19 + @Bean
  20 + public GroupedOpenApi mpGroupedOpenApi() {
  21 + return YudaoSwaggerAutoConfiguration.buildGroupedOpenApi("mp");
  22 + }
  23 +
  24 +}
yudao-module-mp/yudao-module-mp-biz/src/main/java/cn/iocoder/yudao/module/mp/framework/web/package-info.java 0 → 100644
  View file @711a39b
  1 +/**
  2 + * mp 模块的 web 配置
  3 + */
  4 +package cn.iocoder.yudao.module.mp.framework.web;
yudao-module-pay/yudao-module-pay-biz/src/main/java/cn/iocoder/yudao/module/pay/framework/web/config/PayWebConfiguration.java 0 → 100644
  View file @711a39b
  1 +package cn.iocoder.yudao.module.pay.framework.web.config;
  2 +
  3 +import cn.iocoder.yudao.framework.swagger.config.YudaoSwaggerAutoConfiguration;
  4 +import org.springdoc.core.GroupedOpenApi;
  5 +import org.springframework.context.annotation.Bean;
  6 +import org.springframework.context.annotation.Configuration;
  7 +
  8 +/**
  9 + * pay 模块的 web 组件的 Configuration
  10 + *
  11 + * @author 芋道源码
  12 + */
  13 +@Configuration(proxyBeanMethods = false)
  14 +public class PayWebConfiguration {
  15 +
  16 + /**
  17 + * pay 模块的 API 分组
  18 + */
  19 + @Bean
  20 + public GroupedOpenApi payGroupedOpenApi() {
  21 + return YudaoSwaggerAutoConfiguration.buildGroupedOpenApi("pay");
  22 + }
  23 +
  24 +}
yudao-module-pay/yudao-module-pay-biz/src/main/java/cn/iocoder/yudao/module/pay/framework/web/package-info.java 0 → 100644
  View file @711a39b
  1 +/**
  2 + * pay 模块的 web 配置
  3 + */
  4 +package cn.iocoder.yudao.module.pay.framework.web;
yudao-module-system/yudao-module-system-biz/src/main/java/cn/iocoder/yudao/module/system/framework/web/config/SystemWebConfiguration.java 0 → 100644
  View file @711a39b
  1 +package cn.iocoder.yudao.module.system.framework.web.config;
  2 +
  3 +import cn.iocoder.yudao.framework.swagger.config.YudaoSwaggerAutoConfiguration;
  4 +import org.springdoc.core.GroupedOpenApi;
  5 +import org.springframework.context.annotation.Bean;
  6 +import org.springframework.context.annotation.Configuration;
  7 +
  8 +/**
  9 + * system 模块的 web 组件的 Configuration
  10 + *
  11 + * @author 芋道源码
  12 + */
  13 +@Configuration(proxyBeanMethods = false)
  14 +public class SystemWebConfiguration {
  15 +
  16 + /**
  17 + * system 模块的 API 分组
  18 + */
  19 + @Bean
  20 + public GroupedOpenApi systemGroupedOpenApi() {
  21 + return YudaoSwaggerAutoConfiguration.buildGroupedOpenApi("system");
  22 + }
  23 +
  24 +}
yudao-module-system/yudao-module-system-biz/src/main/java/cn/iocoder/yudao/module/system/framework/web/package-info.java 0 → 100644
  View file @711a39b
  1 +/**
  2 + * system 模块的 web 配置
  3 + */
  4 +package cn.iocoder.yudao.module.system.framework.web;
yudao-server/pom.xml
  View file @711a39b
@@ -41,19 +41,19 @@ @@ -41,19 +41,19 @@
41 <artifactId>yudao-spring-boot-starter-biz-error-code</artifactId> 41 <artifactId>yudao-spring-boot-starter-biz-error-code</artifactId>
42 </dependency> 42 </dependency>
43 43
44 - <!-- 数据报表 -->  
45 -<!-- <dependency>-->  
46 -<!-- <groupId>cn.iocoder.boot</groupId>-->  
47 -<!-- <artifactId>yudao-module-visualization-biz</artifactId>-->  
48 -<!-- <version>${revision}</version>-->  
49 -<!-- </dependency>-->  
50 - <!-- 工作流 --> 44 + <!-- 数据报表。默认注释，保证编译速度 -->
  45 + <dependency>
  46 + <groupId>cn.iocoder.boot</groupId>
  47 + <artifactId>yudao-module-visualization-biz</artifactId>
  48 + <version>${revision}</version>
  49 + </dependency>
  50 + <!-- 工作流。默认注释，保证编译速度 -->
51 <!-- <dependency>--> 51 <!-- <dependency>-->
52 <!-- <groupId>cn.iocoder.boot</groupId>--> 52 <!-- <groupId>cn.iocoder.boot</groupId>-->
53 <!-- <artifactId>yudao-module-bpm-biz</artifactId>--> 53 <!-- <artifactId>yudao-module-bpm-biz</artifactId>-->
54 <!-- <version>${revision}</version>--> 54 <!-- <version>${revision}</version>-->
55 <!-- </dependency>--> 55 <!-- </dependency>-->
56 - <!-- 支付服务 --> 56 + <!-- 支付服务。默认注释，保证编译速度 -->
57 <dependency> 57 <dependency>
58 <groupId>cn.iocoder.boot</groupId> 58 <groupId>cn.iocoder.boot</groupId>
59 <artifactId>yudao-module-pay-biz</artifactId> 59 <artifactId>yudao-module-pay-biz</artifactId>
yudao-server/src/main/resources/application.yaml
  View file @711a39b
@@ -34,8 +34,9 @@ spring: @@ -34,8 +34,9 @@ spring:
34 redis: 34 redis:
35 time-to-live: 1h # 设置过期时间为 1 小时 35 time-to-live: 1h # 设置过期时间为 1 小时
36 36
  37 +--- #################### 接口文档配置 ####################
  38 +
37 springdoc: 39 springdoc:
38 - show-actuator: true  
39 swagger-ui: 40 swagger-ui:
40 enabled: true 41 enabled: true
41 path: /swagger-ui 42 path: /swagger-ui