本次和大家分享的是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 = "登錄賬號")：請求響應屬性上的標記，用來描述該屬性具體說明

快速構建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能夠得到如下成功運行的效果圖：

　　

?

git地址： https://github.com/shenniubuxing3????nuget發布包：https://www.nuget.org/profiles/shenniubuxing3

總結

以上是生活随笔為你收集整理的springmvc+swagger构建Restful风格文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。