📝 更新文档:swagger的配置与使用说明

doc/md/swagger.md

@@ -1,6 +1,114 @@
-# 如何在pigx Swagger中OAuth2.0 授权
+# Swagger配置文档
 
-## 增加客户端
+### 写在最前
+pigX集成了Swagger作为API生成与测试框架,pigX提供了自动化的配置，让您从繁琐的编码工作中解放出来，快速生成自己定制化的Swagger API文档。
+
+### 快速使用
+您可以轻松地在pigX中引入Swagger:   
+
+- 在`pom.xml`中引入以下依赖:
+
+```xml
+		<dependency>
+			<groupId>com.pig4cloud</groupId>
+			<artifactId>pigx-common-swagger</artifactId>
+		</dependency>
+```
+
+- 在应用主类中增加`@EnablePigxSwagger2`注解
+
+```java
+@EnablePigxSwagger2
+@EnableFeignClients
+@SpringCloudApplication
+public class PigxAdminApplication {
+	public static void main(String[] args) {
+		SpringApplication.run(PigxAdminApplication.class, args);
+	}
+}
+```
+
+只需以上两步，就能产生当前工程中Spring MVC加载的请求映射所形成的文档。如需要个性化的定制，请看下文。
+
+### 配置示例与说明
+
+```
+# Swagger相关的配置
+swagger:
+  # 标题,默认空
+  title: 'PigX Swagger API'
+  # 描述,默认空
+  description: '全宇宙最牛逼的Spring Cloud微服务开发脚手架'
+  # 版本,默认空
+  version: '1.3.0'
+  # 许可证,默认空
+  license: 'Powered By PigX'
+  # 许可证URL,默认空
+  licenseUrl: 'https://gitee.com/log4j/pig/wikis'
+  # 服务条款URL,默认空
+  terms-of-service-url: 'https://gitee.wang/pig/pigx'
+  # 文档的host信息，默认：空
+  host: 'https://gitee.wang/pig/pigx'
+  # swagger会解析的包路径,默认为空，扫描所有包
+  base-package: '' 
+  # swagger会解析的url规则
+  base-path: /**
+  # 在basePath基础上需要排除的url规则
+  exclude-path: 
+    - /actuator/**
+    - /error  
+  # 联系人相关配置
+  contact:
+    # 联系人姓名，默认空
+    name: '冷冷'
+    # 联系人Email，默认空
+    email: 'wangiegie@gmail.com'
+    # 联系人URL，默认空
+    url: 'https://gitee.wang/pig/pigx'
+  # 统一鉴权相关配置
+  authorization:
+    # 鉴权策略名称，默认空
+    name: 'pigX OAuth'
+    # 需要开启鉴权URL的正则，默认匹配所有
+    auth-regex: '^.*$'
+    # 鉴权作用域列表配置,默认空
+    authorization-scope-list:
+        # 鉴权作用域名称,默认空
+      - scope: 'server'
+        # 鉴权作用域描述,默认空
+        description: 'server all'
+    # 校验token的地址列表,默认空  
+    token-url-list:
+      - 'http://localhost:9999/auth/oauth/token'
+
+```
+
+**注意:**
+- 配置中的鉴权作用域`scope`必须是数据库`sys_oauth_client_details`表的`scope`字段里的内容的一个子集，否则发起Oauth2.0请求时会直接失败。
+- 默认情况下Swagger映射Spring MVC中所有的请求,这样的请求包含了排除了Spring Boot默认的监控和异常信息处理路径,通常不是我们想要的。因此提供两种解决方案，任选其一即可。
+- 我们可以使用`swagger.base-path`来指定所有需要生成文档的请求路径基础规则，然后再利用`swagger.exclude-path`来剔除部分我们不需要的。
+我们可以这样设置：
+
+```yaml
+swagger:
+  base-path: /**
+  exclude-path: 
+    - /actuator/**
+    - /error
+```
+
+上面的配置将解析所有除了`/actuator`开始以及spring boot自带`/error`请求路径，这样，就排除了Spring Boot默认的监控和异常信息处理路径。   
+- 除了以上的方法,我们同样可以通过配置包扫描的方式，扫描指定包下的类生成API文档。
+我们可以这样设置：
+
+```yaml
+swagger:
+  base-package: com.pig4cloud.pigx.admin.controller
+```
+这样，Swagger只会生成对应包下的API文档，这样，自然也就排除了Spring Boot默认的监控和异常信息处理路径。
+### 如何在pigx Swagger中OAuth2.0 授权
+
+#### 增加客户端
 
 默认对所有终端进行验证码校验，但是swagger 模拟的时候不需要。
 
@@ -40,7 +148,7 @@ VALUES
 	);
 ```
 
-## 过滤指定客户端
+#### 过滤指定客户端
 
 pigx-gateway-dev.yml
 
@@ -51,8 +159,9 @@ ignore:
     - test
 ```
 
-## 填写客户端信息
+#### 填写客户端信息
 
 ![](http://obq1lvsd9.bkt.clouddn.com/20180725133119.png)
 
-![](http://obq1lvsd9.bkt.clouddn.com/20180725133206.png)
+![](http://obq1lvsd9.bkt.clouddn.com/20180725133206.png)
+