本次和大家分享的是java方面的springmvc來建構的webapi接口+swagger文檔；上篇文章分享.net的webapi用swagger來建構文檔，因為有朋友問了為啥.net有docpage文檔你還用swagger，這裡主要目的是讓接口文檔統一，當操作多種開發語言做接口時，如果有統一風格的api文檔是不是很不錯；還有就springcloude而言，微服務如果有很多的話，使用swagger自動根據服務serverid來加載api文檔是很友善的。swagger設定比較簡單，為了今後查找資料和使用友善故此記錄下
- 準備工作
- 快速建構api文檔
- 常用的細節
- 過濾預設錯誤api
- 添加授權token列
- 添加上傳檔案列
首選需要一個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 = "登入賬号")：請求響應屬性上的标記，用來描述該屬性具體說明
準備做完後要生成文檔，還需要自定義兩個封裝類，如下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("作者：[email protected]")
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能夠得到如下成功運作的效果圖：
git位址：
https://github.com/shenniubuxing3nuget釋出包：
https://www.nuget.org/profiles/shenniubuxing3