Modify api-boot-starter-swagger notes

hengboy · hengboy · commit d5e89cfa970f · 2020-07-06T09:42:41.000+08:00
diff --git a/api-boot-project/api-boot-autoconfigure/src/main/java/org/minbox/framework/api/boot/autoconfigure/swagger/ApiBootSwaggerAutoConfiguration.java b/api-boot-project/api-boot-autoconfigure/src/main/java/org/minbox/framework/api/boot/autoconfigure/swagger/ApiBootSwaggerAutoConfiguration.java
@@ -1,5 +1,6 @@
 package org.minbox.framework.api.boot.autoconfigure.swagger;
 
+import org.springframework.beans.BeanUtils;
 import org.springframework.beans.factory.BeanFactory;
 import org.springframework.boot.autoconfigure.AutoConfigurationPackages;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
@@ -22,37 +23,30 @@
 import springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration;
 import springfox.documentation.swagger2.web.Swagger2Controller;
 
+import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
 
 import static org.minbox.framework.api.boot.autoconfigure.swagger.SwaggerProperties.API_BOOT_SWAGGER_PREFIX;
 
 /**
- * Swagger2自动化配置
- * 只有在设置api.boot.swagger.enable=true时或者在配置文件内不进行配置时（因为默认为true）才会自动化配置该类
- * 通过@Import导入Swagger原本配置类
+ * Swagger2 automation configuration
+ * Only when setting "api.boot.swagger.enable=true" or when no configuration in the configuration file (because the default is true) will automatically configure this class
+ * Import the original configuration class of Swagger through @Import
  *
- * @author：恒宇少年 - 于起宇
- * <p>
- * DateTime：2019-03-16 23:41
- * Blog：http://blog.yuqiyu.com
- * WebSite：http://www.jianshu.com/u/092df3f77bca
- * Gitee：https://gitee.com/hengboy
- * GitHub：https://github.com/hengboy
+ * @author 恒宇少年
  */
 @Configuration
 @EnableConfigurationProperties(SwaggerProperties.class)
 @ConditionalOnClass({SwaggerCommonConfiguration.class, Swagger2DocumentationConfiguration.class, Swagger2Controller.class})
 @ConditionalOnProperty(prefix = API_BOOT_SWAGGER_PREFIX, name = "enable", havingValue = "true", matchIfMissing = true)
 @Import({Swagger2DocumentationConfiguration.class, BeanValidatorPluginsConfiguration.class})
 public class ApiBootSwaggerAutoConfiguration {
-    /**
-     * swagger相关属性配置
-     */
+    private static final String AUTHORIZATION_SCOPE = "global";
+    private static final String AUTHORIZATION_SCOPE_DESCRIPTION = "accessEverything";
     private SwaggerProperties swaggerProperties;
-    /**
-     * spring bean factory
-     */
     private BeanFactory beanFactory;
 
     public ApiBootSwaggerAutoConfiguration(SwaggerProperties swaggerProperties, BeanFactory beanFactory) {
@@ -61,59 +55,97 @@ public ApiBootSwaggerAutoConfiguration(SwaggerProperties swaggerProperties, Bean
     }
 
     /**
-     * 配置swagger基本信息
-     * - BasePackage
-     * 默认使用SpringBoot项目扫描bean根目录
-     * 如果存在配置时则使用SwaggerProperties.basePackage作为扫描根目录
+     * Configure {@link Docket}
+     * <p>
+     * The base package value:
+     * default value is {@link SwaggerProperties#getBasePackage()}，if is it empty
+     * the {@link AutoConfigurationPackages#get} is used
      *
-     * @return Docket实例
+     * @return The {@link Docket} instance
      */
     @Bean
     public Docket docket() {
         String basePackage = swaggerProperties.getBasePackage();
         if (StringUtils.isEmpty(basePackage)) {
             basePackage = AutoConfigurationPackages.get(beanFactory).get(0);
         }
-        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).securitySchemes(Collections.singletonList(apiKey())).securityContexts(Collections.singletonList(securityContext())).select().apis(RequestHandlerSelectors.basePackage(basePackage)).paths(PathSelectors.any()).build();
+        return new Docket(DocumentationType.SWAGGER_2)
+            .apiInfo(apiInfo())
+            .securitySchemes(Collections.singletonList(apiKey()))
+            .securityContexts(Collections.singletonList(securityContext()))
+            .select()
+            .apis(RequestHandlerSelectors.basePackage(basePackage))
+            .paths(PathSelectors.any())
+            .build();
     }
 
     /**
-     * 配置文档基本信息
-     * 如：文档标题、版本、描述、联系人基本信息等
+     * Configure {@link ApiInfo}
      *
-     * @return ApiInfo实例
+     * @return The {@link ApiInfo} instance
      */
     public ApiInfo apiInfo() {
-        return new ApiInfoBuilder().title(swaggerProperties.getTitle()).description(swaggerProperties.getDescription()).version(swaggerProperties.getVersion()).license(swaggerProperties.getLicense()).licenseUrl(swaggerProperties.getLicenseUrl()).contact(new Contact(swaggerProperties.getContact().getName(), swaggerProperties.getContact().getWebsite(), swaggerProperties.getContact().getEmail())).build();
+        Contact contact = this.convertContact(swaggerProperties.getContact());
+        return new ApiInfoBuilder()
+            .title(swaggerProperties.getTitle())
+            .description(swaggerProperties.getDescription())
+            .version(swaggerProperties.getVersion())
+            .license(swaggerProperties.getLicense())
+            .licenseUrl(swaggerProperties.getLicenseUrl())
+            .contact(contact)
+            .build();
     }
 
     /**
-     * 配置Swagger整合Oauth2时的请求Key信息
-     * 使用头部传递方式 Authorization: Beare TokenValue
+     * Request key information when configuring Swagger to integrate Oauth2
+     * <p>
+     * Use header transfer {@link ApiKeyVehicle#HEADER} method "Authorization: Bearer TokenValue"
      *
-     * @return apiKey
+     * @return The {@link ApiKey} instance
      */
     private ApiKey apiKey() {
-        return new ApiKey(swaggerProperties.getAuthorization().getName(), swaggerProperties.getAuthorization().getKeyName(), ApiKeyVehicle.HEADER.getValue());
+        return new ApiKey(swaggerProperties.getAuthorization().getName(),
+            swaggerProperties.getAuthorization().getKeyName(),
+            ApiKeyVehicle.HEADER.getValue());
     }
 
     /**
-     * 配置安全上下文
+     * Configure {@link SecurityContext}
      *
-     * @return securityContext
+     * @return The {@link SecurityContext} instance
      */
     private SecurityContext securityContext() {
-        return SecurityContext.builder().securityReferences(this.defaultAuth()).forPaths(PathSelectors.regex(swaggerProperties.getAuthorization().getAuthRegex())).build();
+        return SecurityContext.builder()
+            .securityReferences(this.defaultAuth())
+            .forPaths(PathSelectors.regex(swaggerProperties.getAuthorization().getAuthRegex()))
+            .build();
     }
 
     /**
-     * 配置默认权限
+     * Configure {@link SecurityReference}
+     * <p>
+     * The configured reference will be displayed on the dialog
      *
-     * @return SecurityReference arrays
+     * @return The {@link SecurityReference} list
      */
     private List<SecurityReference> defaultAuth() {
-        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
-        AuthorizationScope[] authorizationScopes = new AuthorizationScope[]{authorizationScope};
-        return Collections.singletonList(SecurityReference.builder().reference(swaggerProperties.getAuthorization().getName()).scopes(authorizationScopes).build());
+        AuthorizationScope authorizationScope = new AuthorizationScope(AUTHORIZATION_SCOPE, AUTHORIZATION_SCOPE_DESCRIPTION);
+        AuthorizationScope[] authorizationScopes = Arrays.asList(authorizationScope).stream().toArray(AuthorizationScope[]::new);
+        SecurityReference securityReference =
+            SecurityReference.builder()
+                .reference(swaggerProperties.getAuthorization().getName())
+                .scopes(authorizationScopes)
+                .build();
+        return Collections.singletonList(securityReference);
+    }
+
+    /**
+     * Convert {@link SwaggerProperties.Contact} to {@link Contact}
+     *
+     * @param contact The {@link SwaggerProperties.Contact} instance
+     * @return {@link Contact} instance
+     */
+    private Contact convertContact(SwaggerProperties.Contact contact) {
+        return new Contact(contact.getName(), contact.getWebsite(), contact.getEmail());
     }
 }
diff --git a/api-boot-project/api-boot-autoconfigure/src/main/java/org/minbox/framework/api/boot/autoconfigure/swagger/SwaggerProperties.java b/api-boot-project/api-boot-autoconfigure/src/main/java/org/minbox/framework/api/boot/autoconfigure/swagger/SwaggerProperties.java
@@ -1,102 +1,100 @@
 package org.minbox.framework.api.boot.autoconfigure.swagger;
 
 import lombok.Data;
+import lombok.experimental.Accessors;
 import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.springframework.context.annotation.Configuration;
 
 import static org.minbox.framework.api.boot.autoconfigure.swagger.SwaggerProperties.API_BOOT_SWAGGER_PREFIX;
 
 /**
- * swagger属性配置
+ * Swagger config properties
  *
- * @author：恒宇少年 - 于起宇
- * <p>
- * DateTime：2019-03-16 23:39
- * Blog：http://blog.yuqiyu.com
- * WebSite：http://www.jianshu.com/u/092df3f77bca
- * Gitee：https://gitee.com/hengboy
- * GitHub：https://github.com/hengboy
+ * @author 恒宇少年
+ * @see ApiBootSwaggerAutoConfiguration
  */
 @Data
 @Configuration
 @ConfigurationProperties(prefix = API_BOOT_SWAGGER_PREFIX)
 public class SwaggerProperties {
     /**
-     * swagger配置前缀
+     * Swagger config properties prefix
      */
     public static final String API_BOOT_SWAGGER_PREFIX = "api.boot.swagger";
     /**
-     * 是否开启文档，默认开启
+     * Whether to open the document
+     * open by default
      */
     private boolean enable = true;
     /**
-     * swagger扫描本项目的base-package
-     * 扫描该package下的所有controller来生成文档
+     * Scan all controllers under this package to generate documents
      */
     private String basePackage;
     /**
-     * 文档标题
+     * Document title
      */
     private String title = "ApiBoot快速集成Swagger文档";
     /**
-     * 文档描述
+     * Document description
      */
     private String description = "ApiBoot通过自动化配置快速集成Swagger2文档，仅需一个注解、一个依赖即可。";
     /**
-     * 文档版本号
+     * Document version
+     * <p>
+     * Same as ApiBoot version
      */
-    private String version = "2.2.6.RELEASE";
+    private String version = "2.2.7-SNAPSHOT";
     /**
-     * 文档版权
+     * Document copyright owner
      */
     private String license = "ApiBoot";
     /**
-     * 文档版权路径
+     * Document copyright path
      */
     private String licenseUrl = "https://github.com/hengboy/api-boot";
     /**
-     * 文档编写联系人信息
+     * Document writing contact
      */
     private Contact contact = new Contact();
     /**
-     * 文档接口访问时认证信息
+     * Authentication information when accessing the document interface
      */
     private Authorization authorization = new Authorization();
 
     /**
-     * 文档编写联系人信息
+     * Document contact
      */
     @Data
     public static class Contact {
         /**
-         * 联系人名称
+         * Contact name
          */
         private String name = "恒宇少年";
         /**
-         * 联系人主页
+         * Contact website
          */
         private String website = "http://blog.yuqiyu.com";
         /**
-         * 联系人邮箱地址
+         * Contact mail address
          */
         private String email = "jnyuqy@gmail.com";
     }
 
     /**
-     * 文档接口访问所需认证配置信息
+     * Document authorization
      */
     @Data
     public static class Authorization {
         /**
-         * 整合Oauth2后授权名称
+         * Authorization description
          */
         private String name = "ApiBoot Security Oauth 认证头信息";
         /**
-         * 整合Oauth2后授权请求头Header内的key-name
+         * Authorization head name
          */
         private String keyName = "Authorization";
         /**
-         * 整合Oauth2后授权表达式
+         * Authorization expression
          */
         private String authRegex = "^.*$";
     }
diff --git a/api-boot-project/api-boot-autoconfigure/src/main/java/org/minbox/framework/api/boot/autoconfigure/swagger/annotation/EnableApiBootSwagger.java b/api-boot-project/api-boot-autoconfigure/src/main/java/org/minbox/framework/api/boot/autoconfigure/swagger/annotation/EnableApiBootSwagger.java
@@ -6,15 +6,9 @@
 import java.lang.annotation.*;
 
 /**
- * 使用该注解开启ApiBoot整合Swagger2文档
+ * Use this annotation to open the ApiBoot integration Swagger2 document
  *
- * @author：恒宇少年 - 于起宇
- * <p>
- * DateTime：2019-03-17 08:58
- * Blog：http://blog.yuqiyu.com
- * WebSite：http://www.jianshu.com/u/092df3f77bca
- * Gitee：https://gitee.com/hengboy
- * GitHub：https://github.com/hengboy
+ * @author 恒宇少年
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.TYPE})
