微服務架構實戰篇（二）：Spring boot2.0 + Swagger2 讓你的API視覺化
簡介
該專案主要利用Spring boot2.0 +Swagger2 方便進行測試後臺的restful形式的介面，實現動態的更新，當我們在後臺的介面修改了後，swagger可以實現自動的更新，而不需要認為的維護這個介面進行測試。
- 原始碼地址
- 聯盟公眾號：IT實戰聯盟
- 我們社群：https://100boot.cn
小工具一枚，歡迎使用和Star支援，如使用過程中碰到問題，可以提出Issue，我會盡力完善該Starter
版本基礎
- Spring Boot：2.0.4
- Swagger2：2.7.0
操作步驟
第一步：下載SpringBoot2.0專案
- GitHub地址：https://github.com/yundianzixun/spring-boot-starter
- 參考文件：https://www.jianshu.com/p/7dc2240f010e
第二步：新增maven依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>org.apache.tomcat.embed</groupId>
<artifactId>tomcat-embed-jasper</artifactId>
</dependency>
<!-- 打war包用 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
第三步：application.properties 增加swagger配置
#開啟swagger服務
swagger.enable=true
第四步：使用註解配置Swagger
@Configuration
@EnableSwagger2
public class Swagger2Config {
public static final String BASE_PACKAGE = "com.itunion";
@Value("${swagger.enable}")
private boolean enableSwagger;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) // 生產環境的時候關閉 swagger 比較安全
.enable(enableSwagger) //將Timestamp型別全部轉為Long型別
.directModelSubstitute(Timestamp.class, Long.class) //將Date型別全部轉為Long型別
.directModelSubstitute(Date.class, Long.class)
.select() // 掃描介面的包路徑，不要忘記改成自己的
.apis(RequestHandlerSelectors.basePackage(BASE_PACKAGE))
.paths(PathSelectors.any())
.build();
} private ApiInfo apiInfo() { return new ApiInfoBuilder()
.title("Swagger RESTful APIs")
.description("Swagger API 服務")
.termsOfServiceUrl("http://swagger.io/")
.contact(new Contact("Swagger", "127.0.0.1", "[email protected]"))
.version("1.0")
.build();
}
}
備註
- 正常專案上線後應該是關閉掉 swagger 的，所以這邊增加了一個配置 enableSwagger
- 可以使用 directModelSubstitute 做一些期望的型別轉換
第五步：建立使用者實體類UserInfo
public class UserInfo {
@ApiModelProperty("編號")
private Long id;
@ApiModelProperty("使用者名稱")
private String userName;
@ApiModelProperty("姓")
private String firstName;
@ApiModelProperty("名")
private String lastName;
@ApiModelProperty("郵箱")
private String email;
@ApiModelProperty(hidden = true)// 密碼不傳輸
@JsonIgnore
private String password;
@ApiModelProperty("狀態")
private Integer userStatus;
/**此處省略get、set **/
}
第六步：編寫一個首頁的Controller
@Api(value = "首頁", description = "首頁")
@RequestMapping("/")
@RestController
public class IndexController {
@ApiOperation(value = "Hello Spring Boot", notes = "Hello Spring Boot")
@RequestMapping(value = "/", method = RequestMethod.GET)
public String index() {
return "Hello Spring Boot";
}
@ApiOperation(value = "API 頁面", notes = "介面列表")
@RequestMapping(value = "/api", method = RequestMethod.GET)
public void api(HttpServletResponse response) throws IOException {
response.sendRedirect("swagger-ui.html");
}
}
- 為了方便訪問swagger ui 頁面，我們做了一個重定向 api 更方便些
第七步：編寫一個登陸的Controller
@Api(value = "使用者", description = "使用者")
@RequestMapping("/userInfo")
@RestController
public class UserInfoController {
@ApiOperation(value = "登入介面-多值傳值方式", notes = "輸入使用者名稱和密碼登入")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "OK", response = UserInfo.class, responseContainer = "userInfo"),
@ApiResponse(code = 405, message = "賬號名或密碼錯誤")
})
@ApiImplicitParam(name = "map", value = "{\"userName\":\"JackMa\",\"passWord\":\"123\"}")
@RequestMapping(value = "loginForMap", method = RequestMethod.POST, produces= MediaType.APPLICATION_JSON_UTF8_VALUE)
ResponseEntity<UserInfo> loginForMap(@RequestBody Map<String, String> map) {
if (!map.get("userName").equalsIgnoreCase("JackMa") || !map.get("passWord").equalsIgnoreCase("123")) {
return ResponseEntity.status(HttpStatus.METHOD_NOT_ALLOWED).build();
}
UserInfo user = new UserInfo();
user.setId(1L);
user.setUserName("JackMa");
user.setFirstName("馬");
user.setLastName("雲");
user.setEmail("[email protected]");
user.setUserStatus(1);
return ResponseEntity.ok(user);
}
@ApiOperation(value = "登入介面-多值傳輸方式", notes = "輸入使用者名稱和密碼登入")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "OK", response = UserInfo.class, responseContainer = "userInfo"),
@ApiResponse(code = 405, message = "賬號名或密碼錯誤")
})
@ApiImplicitParams({
@ApiImplicitParam(name = "userName",value = "使用者名稱", required = true, dataType = "string", paramType = "query"),
@ApiImplicitParam(name = "passWord",value = "密碼", required = true, dataType = "string",paramType = "query"),
})
@RequestMapping(value = "loginForParams", method = RequestMethod.POST, produces= MediaType.APPLICATION_JSON_UTF8_VALUE)
ResponseEntity<UserInfo> loginForMap(@RequestParam String userName, @RequestParam String passWord) {
if (!userName.equalsIgnoreCase("JackMa") || !passWord.equalsIgnoreCase("123")) {
return ResponseEntity.status(HttpStatus.METHOD_NOT_ALLOWED).build();
}
UserInfo user = new UserInfo();
user.setId(1L);
user.setUserName("JackMa");
user.setFirstName("馬");
user.setLastName("雲");
user.setEmail("[email protected]");
user.setUserStatus(1);
return ResponseEntity.ok(user);
}
}
備註
- 使用Params和Param 實現了兩種不同的資料傳輸方式
- 建議使用Spring的 ResponseEntity 類做統一的返回結果
- swagger 對 response code 的支援還算好，我們可以把可能出現的異常程式碼都一一羅列出來，方便對接的時候對異常的處理
第八步：啟動執行
http://127.0.0.1:8081/api
備註
- 埠號已自己配置為準
如下圖所示：
swagger2.jpg
第九步：執行
輸入.jpg
輸出.jpg
貢獻者
更多精彩內容可以關注“IT實戰聯盟”微信*公*眾*號哦~~~