springmvc+swagger構建Restful風格文檔

　　本次和你們分享的是java方面的springmvc來構建的webapi接口+swagger文檔；上篇文章分享.net的webapi用swagger來構建文檔，由於有朋友問了爲啥.net有docpage文檔你還用swagger，這裏主要目的是讓接口文檔統一，當操做多種開發語言作接口時，若是有統一風格的api文檔是否是很不錯；還有就springcloude而言，微服務若是有不少的話，使用swagger自動根據服務serverid來加載api文檔是很方便的。swagger設置比較簡單，爲了從此查找資料和使用方便故此記錄下

• 準備工做
• 快速構建api文檔
• 經常使用的細節

1. 過濾默認錯誤api
2. 添加受權token列
3. 添加上傳文件列

準備工做

　　首選須要一個springmvc項目，這裏我用的是springboot+maven來快速構建， 要使用swagger只須要在maven中添加依賴包就行：

 1 <dependency>
 2     <groupId>io.springfox</groupId>
 3     <artifactId>springfox-swagger2</artifactId>
 4     <version>2.6.1</version>
 5 </dependency>
 6 <dependency>
 7     <groupId>io.springfox</groupId>
 8     <artifactId>springfox-swagger-ui</artifactId>
 9     <version>2.6.1</version>
10 </dependency>

　　而後建立一個UserController，而後再定義個Login的Action，定義請求和響應實體，因爲api接口須要對請求和響應屬性列作 文字描述，而且上面咱們在項目中加了swagger包，所以以直接在實體和Action使用特性來增長具體文字描述：

 1 @RestController
 2 @Api(tags = "會員接口")
 3 public class UserController {
 4 
 5     @PostMapping("/login")
 6     @ApiOperation(value = "登陸")
 7     public LoginRp login(@RequestBody LoginRq rq) {
 8         LoginRp rp = new LoginRp();
 9 
10         if (rq.getUserName().isEmpty() || rq.getUserPwd().isEmpty()) {
11             rp.setCode(EmApiCode.登陸帳號或密碼不能爲空.getVal());
12             return rp;
13         }
14 
15         if (rq.getUserName().equals("shenniu001") && rq.getUserPwd().equals("123")) {
16             rp.setCode(EmApiCode.成功.getVal());
17 
18             rp.setToken(UUID.randomUUID().toString());
19         } else {
20             rp.setCode(EmApiCode.失敗.getVal());
21         }
22         return rp;
23     }
24 
25 }

　　請求和響應實體類：

 1 @ApiModel
 2 public class LoginRq implements Serializable{
 3 
 4     private static final long serialVersionUID = -158328750073317876L;
 5 
 6     @ApiModelProperty(value = "登陸帳號")
 7     private String userName;
 8 
 9     @ApiModelProperty(value = "登陸密碼")
10     private String userPwd;
11 
12 }
13 
14 @ApiModel
15 public class LoginRp extends BaseRp implements Serializable {
16     private static final long serialVersionUID = -1486838360296425228L;
17 
18     @ApiModelProperty(value = "受權token")
19     private String token;
20 
21     public String getToken() {
22         return token;
23     }
24 
25     public void setToken(String token) {
26         this.token = token;
27     }
28 }

View Code

　　註解簡單說明：

　　@Api：同一類接口的總描述，通常用於Controller標記

　　@ApiOperation(value = "登陸")：在Action上標記，描述這個Action接口具體幹什麼

　　@ApiModel：請求響應實體類class上的標記

　　@ApiModelProperty(value = "登陸帳號")：請求響應屬性上的標記，用來描述該屬性具體說明

快速構建api文檔

　　準備作完後要生成文檔，還須要自定義兩個封裝類，以下Swagger2類：

 1 @Configuration
 2 @EnableSwagger2
 3 public class Swagger2 {
 4 
 5     @Bean
 6     public Docket createRestApi() {
 7 
 8         return new Docket(DocumentationType.SWAGGER_2)
 9                 .select()
10                 //過濾默認錯誤api
11                 .paths(Predicates.not(PathSelectors.regex("/error.*")))
12                 .build()
13                 .apiInfo(apiInfo());
14     }
15 
16     //經常使用的細節
17     //過濾指定的action
18     //添加受權token列
19     //添加上傳文件列
20     private ApiInfo apiInfo() {
21         return new ApiInfoBuilder()
22                 .title("開車接口文檔")
23                 .description("該文檔只容許我使用")
24                 //版本
25                 .version("0.0.0.1")
26                 .contact("做者：841202396@qq.com")
27                 .build();
28     }
29 }

　　這個類主要初始化一些全局文檔的說明和版本而且構架api文檔；上面是生成文檔，可是具體文檔數據源用從swagger的SwaggerResourcesProvider中來，所以自定義的DocumentationConfig類實現SwaggerResourcesProvider接口，以下：

 1 @Component
 2 @Primary
 3 public class DocumentationConfig implements SwaggerResourcesProvider {
 4     @Override
 5     public List<SwaggerResource> get() {
 6         List resources = new ArrayList<>();
 7         resources.add(swaggerResource("開車接口api", "/v2/api-docs", "0.0.0.1"));
 8         resources.add(swaggerResource("坐車接口api", "/v2/api-docs", "0.0.0.1"));
 9         return resources;
10     }
11 
12     private SwaggerResource swaggerResource(String name, String location, String version) {
13         SwaggerResource swaggerResource = new SwaggerResource();
14         swaggerResource.setName(name);
15         swaggerResource.setLocation(location);
16         swaggerResource.setSwaggerVersion(version);
17         return swaggerResource;
18     }
19 }

　　主要加載文檔的數據源，數據源主要經過 resources.add(swaggerResource("坐車接口api", "/v2/api-docs", "0.0.0.1")) 添加，假若你想添加其餘api接口源就能夠在這裏進行配置，直接把/v2/api-docs改爲你的url就行，這個地方也是springcloud微服務api添加的入口；當編碼完成後咱們來看看效果：

　　

　　能成功加載出咱們的login接口，並且有一些說明性的文字；再來看看咱們請求和響應的參數是否有說明：

　　

　　請求和響應都有了相應的說明，是否是挺簡單；

經常使用的細節

　　1.過濾默認錯誤api

　　因爲springmvc封裝有錯誤的controller，所以swagger也會把這個展現出來，由於是掃描的全部controller來展現swagger文檔的，故此咱們須要屏蔽這些對於對接方沒用的接口；這裏經過設置paths的不匹配就好了，如下代碼：

1 //過濾默認錯誤api
2 paths(Predicates.not(PathSelectors.regex("/error.*")))

　　2.添加受權token列

　　對於接口驗證來講一般須要個token而且放在header裏面，這裏咱們直接在swagger上增長一個顯示的token，只須要在build以前增長一個header參數：

 1 @Bean
 2     public Docket createRestApi() {
 3 
 4         List<Parameter> pars = new ArrayList<>();
 5         //添加受權token
 6         ParameterBuilder tokenPar = new ParameterBuilder();
 7         tokenPar.name("token").description("受權token 注：登陸不須要填，只有post方式的接口必填").
 8                 modelRef(new ModelRef("string")).
 9                 parameterType("header").required(false).build();
10         pars.add(tokenPar.build());
11 
12         return new Docket(DocumentationType.SWAGGER_2)
13                 .select()
14                 .paths(Predicates.not(PathSelectors.regex("/error.*")))
15                 .build()
16                 .globalOperationParameters(pars)
17                 .apiInfo(apiInfo());
18    }

　　這個時候每一個action接口文檔塊中都會增長一個token列，type是header類型：

　　

　　3.添加上傳文件列

　　一般api接口都包含一個公共上傳接口，爲了讓swagger文檔更方便，咱們須要讓她支持下上傳；首先這樣定義一個上傳接口：

1 @PostMapping(value = "/upload",headers = "content-type=multipart/form-data")
2     @ApiOperation(value = "上傳")
3     public BaseRp upload(@ApiParam(value = "上傳的文件",required = true) @RequestBody MultipartFile file) {
4         BaseRp rp = new BaseRp();
5 
6         rp.setMessage("上傳文件名："+file.getOriginalFilename());
7 
8         return rp;
9     }

　　其餘就不用再設置了，僅僅如此運行後效果：

　　

　　咋們點擊「選擇文件」測試下上傳，點擊try可以獲得以下成功運行的效果圖：