Merge pull request #68 from gumutianqi/master

新增Swagger的Authorization全局授权功能

Author: 程序猿DD-翟永超

README.md

@@ -16,23 +16,25 @@
 # 版本基础
 
 - Spring Boot：1.5.x
-- Swagger：2.7.x
+- Swagger：2.8.x
 
 # 如何使用
 
 在该项目的帮助下，我们的Spring Boot可以轻松的引入swagger2，主需要做下面两个步骤：
 
 - 在`pom.xml`中引入依赖：
 
+> 当前最新版本 1.7.0.RELEASE
+
 ```xml
 <dependency>
 	<groupId>com.spring4all</groupId>
 	<artifactId>swagger-spring-boot-starter</artifactId>
-	<version>1.6.0.RELEASE</version>
+	<version>1.7.0.RELEASE</version>
 </dependency>
 ```
 
-**注意：从`1.6.0`开始，我们按Spring Boot官方建议修改了artifactId为`swagger-spring-boot-starter`，1.6.0之前的版本不做修改，依然为使用`spring-boot-starter-swagger` !**
+**注意：从`1.6.1`开始，我们按Spring Boot官方建议修改了artifactId为`swagger-spring-boot-starter`，1.6.0之前的版本不做修改，依然为使用`spring-boot-starter-swagger` !**
 
 - 在应用主类中增加`@EnableSwagger2Doc`注解
 
@@ -249,13 +251,102 @@ swagger.ui-config.submit-methods=get,delete
 swagger.ui-config.submit-methods=
 ```
 
+---
+
+### 来自2018年的版本升级，欢呼吧，Coder们
+
+> 2018-03-21 今日春分，细雨如风 `1.7.0` 版本诞生 @gumutianqi
+
+#### UI升级到 2.8.0 版本 (1.7.0 + 支持)
+
+- 扁平化设计
+- 更加华丽
+- 更加易用
+- 可配置项更加自由
+
+
+### Authorization 鉴权配置 (1.7.0 + 支持)
+
+- 新增 Authorization 配置项
+
+```properties
+# 鉴权策略ID，对应 SecurityReferences ID
+swagger.authorization.name=Authorization
+
+# 鉴权传递的Header参数
+swagger.authorization.key-name=token
+
+# 需要开启鉴权URL的正则, 默认^.*$匹配所有URL
+swagger.authorization.auth-regex=^.*$
+```
+
+备注：目前支持`ApiKey`鉴权模式，后续添加`Oauth2`和`BasicAuth`支持
+
+##### 使用须知
+
+> 1. 默认已经在全局开启了`global`的SecurityReferences，无需配置任何参数就可以使用；
+> 2. 全局鉴权的范围在可以通过以上参数`auth-regex`进行正则表达式匹配控制；
+> 3. 除了全局开启外，还可以手动通过注解在RestController上进行定义鉴权，使用方式如下：
+
+```java
+// 其中的ID Authorization 即为配置项 swagger.authorization.name，详细请关注后面的配置代码
+@ApiOperation(value = "Hello World", authorizations = {@Authorization(value = "Authorization")})
+@RequestMapping(value = "/hello", method = RequestMethod.GET)
+String hello();
+```
+
+##### 关于如何配置实现鉴权，请关注以下code：
+
+```java
+/**
+ * 配置基于 ApiKey 的鉴权对象
+ *
+ * @return
+ */
+private ApiKey apiKey() {
+    return new ApiKey(swaggerProperties().getAuthorization().getName(),
+            swaggerProperties().getAuthorization().getKeyName(),
+            ApiKeyVehicle.HEADER.getValue());
+}
+
+/**
+ * 配置默认的全局鉴权策略的开关，以及通过正则表达式进行匹配；默认 ^.*$ 匹配所有URL
+ * 其中 securityReferences 为配置启用的鉴权策略
+ *
+ * @return
+ */
+private SecurityContext securityContext() {
+    return SecurityContext.builder()
+            .securityReferences(defaultAuth())
+            .forPaths(PathSelectors.regex(swaggerProperties().getAuthorization().getAuthRegex()))
+            .build();
+}
+
+/**
+ * 配置默认的全局鉴权策略；其中返回的 SecurityReference 中，reference 即为ApiKey对象里面的name，保持一致才能开启全局鉴权
+ *
+ * @return
+ */
+private List<SecurityReference> defaultAuth() {
+    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
+    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
+    authorizationScopes[0] = authorizationScope;
+    return Collections.singletonList(SecurityReference.builder()
+            .reference(swaggerProperties().getAuthorization().getName())
+            .scopes(authorizationScopes).build());
+}
+```
+
+
 - 其他配置
 
 ```properties
 # json编辑器
 swagger.ui-config.json-editor=false
+
 # 显示请求头
 swagger.ui-config.show-request-headers=true
+
 # 页面调试请求的超时时间
 swagger.ui-config.request-timeout=5000
 ```
@@ -281,3 +372,4 @@ swagger.docket.aaa.ignored-parameter-types[1]=com.didispace.demo.Product
 - [程序猿DD-翟永超](https://github.com/dyc87112/)
 - [小火](https://renlulu.github.io/)
 - [泥瓦匠BYSocket](https://github.com/JeffLi1993)
+- [LarryKoo-古拉里](https://github.com/gumutianqi)

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.spring4all</groupId>
     <artifactId>swagger-spring-boot-starter</artifactId>
-    <version>1.6.0.RELEASE</version>
+    <version>1.7.0.RELEASE</version>
 
     <name>spring-boot-starter-swagger</name>
     <url>https://github.com/SpringForAll/spring-boot-starter-swagger</url>
@@ -48,8 +48,9 @@
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <version.java>1.8</version.java>
-        <version.swagger>2.7.0</version.swagger>
-        <version.spring-boot>1.5.6.RELEASE</version.spring-boot>
+        <version.swagger>2.8.0</version.swagger>
+        <version.spring-boot>1.5.10.RELEASE</version.spring-boot>
+        <version.lombok>1.16.18</version.lombok>
     </properties>
 
     <dependencies>
@@ -81,7 +82,7 @@
         <dependency>
             <groupId>org.projectlombok</groupId>
             <artifactId>lombok</artifactId>
-            <version>1.16.12</version>
+            <version>${version.lombok}</version>
             <scope>provided</scope>
         </dependency>
         <dependency>