Swagger簡介
前後端分離
- 前端 -> 前端控制層、視圖層
- 後端 -> 後端控制層、服務層、數據訪問層
- 前後端通過API進行交互
- 前後端相對獨立且松耦合
產生的問題
- 前後端集成，前端或者後端無法做到“及時協商，儘早解決”，最終導致問題集中爆發
解決方案
- 首先定義schema [ 計劃的提綱 ]，並實時跟蹤最新的API，降低集成風險
Swagger
- 號稱世界上最流行的API框架
- Restful Api 文檔在線自動生成器 => API 文檔 與API 定義同步更新
- 直接運行，在線測試API
- 支持多種語言 （如：Java，PHP等）
- 官網：https://swagger.io/
SpringBoot集成Swagger
SpringBoot集成Swagger => springfox，兩個jar包
- Springfox-swagger2
- springfox-swagger-ui
使用Swagger
要求：jdk 1.8 + 否則swagger2無法運行
步驟：
-
新建一個SpringBoot-web項目
-
添加Maven依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
-
編寫HelloController，測試確保運行成功！
-
要使用Swagger，我們需要編寫一個配置類-SwaggerConfig來配置 Swagger
@Configuration //配置類
@EnableSwagger2// 開啓Swagger2的自動配置
public class SwaggerConfig {
}
- 訪問測試 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；
配置Swagger
- Swagger實例Bean是Docket，所以通過配置Docket實例來配置Swaggger。
//配置docket以配置Swagger具體參數
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2);
}
- 可以通過apiInfo()屬性配置文檔信息
//配置文檔信息
private ApiInfo apiInfo() {
Contact contact = new Contact("godfrey", "https://www.duiyi.xyz", "[email protected]");
return new ApiInfo(
"Swagger學習", // 標題
"學習如何配置Swagger", // 描述
"v1.0", // 版本
"https://www.duiyi.xyz", // 組織鏈接
contact, // 聯繫人信息
"Apache 2.0", // 許可
"http://www.apache.org/licenses/LICENSE-2.0", // 許可連接
new ArrayList<>()// 擴展
);
}
- Docket 實例關聯上 apiInfo()
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
- 重啓項目，訪問測試 http://localhost:8080/swagger-ui.html 看下效果；
配置掃描接口
- 構建Docket時通過select()方法配置怎麼掃描接口。
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通過.select()方法，去配置掃描接口,RequestHandlerSelectors配置如何掃描接口
.apis(RequestHandlerSelectors.basePackage("com.godfrey.controller"))
.build();
}
-
重啓項目測試，由於我們配置根據包的路徑掃描接口，所以我們只能看到一個類
-
除了通過包路徑配置掃描接口外，還可以通過配置其他方式掃描接口，這裏註釋一下所有的配置方式：
any() // 掃描所有，項目中的所有接口都會被掃描到
none() // 不掃描接口
// 通過方法上的註解掃描，如withMethodAnnotation(GetMapping.class)只掃描get請求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通過類上的註解掃描，如.withClassAnnotation(Controller.class)只掃描有controller註解的類中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根據包路徑掃描接口
- 除此之外，我們還可以配置接口掃描過濾：
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通過.select()方法，去配置掃描接口,RequestHandlerSelectors配置如何掃描接口
.apis(RequestHandlerSelectors.basePackage("com.godfrey.controller"))
.paths(PathSelectors.ant("/godfrey/**"))
.build();
}
- 這裏的可選值還有
any() // 任何請求都掃描
none() // 任何請求都不掃描
regex(final String pathRegex) // 通過正則表達式控制
ant(final String antPattern) // 通過ant()控制
配置Swagger開關
問：如何動態配置當項目處於test、dev環境時顯示swagger，處於prod時不顯示？
答：在Swagger配置類中加上@Profile({“dev”,“test”})，表示在開發（dev）、測試（test）環境中顯示Swagger，在生產（pro）環境中不顯示
配置API分組
- 如果沒有配置分組，默認是default。通過groupName()方法即可配置分組：
@Bean
public Docket docket(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.groupName("對弈") // 配置分組
// 省略配置....
}
-
重啓項目查看分組
-
如何配置多個分組？配置多個分組只需要配置多個docket即可：
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2() {
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3() {
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
- 重啓項目查看即可
實體配置
- 新建一個實體類
@Data
@ApiModel("用戶實體")
public class User {
@ApiModelProperty("用戶名")
private String username;
@ApiModelProperty("密碼")
private String password;
}
- 只要這個實體在請求接口的返回值上（即使是泛型），都能映射到實體項中：
@PostMapping("/getUser")
public User getUser() {
return new User();
}
- 重啓查看測試
注：並不是因爲@ApiModel這個註解讓實體顯示在這裏了，而是隻要出現在接口方法的返回值上的實體都會顯示在這裏，而@ApiModel和@ApiModelProperty這兩個註解只是爲實體添加註釋的。
@ApiModel爲類添加註釋
@ApiModelProperty爲類屬性添加註釋
常用註解
Swagger的所有註解定義在io.swagger.annotations包下
下面列一些經常用到的，未列舉出來的可以另行查閱說明：
| Swagger註解 | 簡單說明 |
|---|---|
| @Api(tags = “xxx模塊說明”) | 作用在模塊類上 |
| @ApiOperation(“xxx接口說明”) | 作用在接口方法上 |
| @ApiModel(“xxxPOJO說明”) | 作用在模型類上：如VO、BO |
| @ApiModelProperty(value = “xxx屬性說明”,hidden = true) | 作用在類方法和屬性上，hidden設置爲true可以隱藏該屬性 |
| @ApiParam(“xxx參數說明”) | 作用在參數、方法和字段上，類似@ApiModelProperty |
我們也可以給請求的接口配置一些註釋
@ApiOperation("對弈的接口")
@PostMapping("/godfrey")
public String godfrey(@ApiParam("用戶名") String username) {
return username;
}
這樣的話，可以給一些比較難理解的屬性或者接口，增加一些配置信息，讓人更容易閱讀！
相較於傳統的Postman或Curl方式測試接口，使用swagger簡直就是傻瓜式操作，不需要額外說明文檔(寫得好本身就是文檔)而且更不容易出錯，只需要錄入數據然後點擊Execute，如果再配合自動化框架，可以說基本就不需要人爲操作了。
Swagger是個優秀的工具，現在國內已經有很多的中小型互聯網公司都在使用它，相較於傳統的要先出Word接口文檔再測試的方式，顯然這樣也更符合現在的快速迭代開發行情。當然了，提醒下大家在正式環境要記得關閉Swagger，一來出於安全考慮二來也可以節省運行時內存。
拓展：其他皮膚
我們可以導入不同的包實現不同的皮膚定義：
- 默認的 訪問 http://localhost:8080/swagger-ui.html
<dependency>-->
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- bootstrap-ui 訪問 http://localhost:8080/doc.html
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
- Layui-ui 訪問 http://localhost:8080/docs.html
<dependency>
<groupId>com.github.caspar-chen</groupId>
<artifactId>swagger-ui-layer</artifactId>
<version>1.1.3</version>
</dependency>
4.mg-ui 訪問 http://localhost:8080/document.html
<dependency>
<groupId>com.zyplayer</groupId>
<artifactId>swagger-mg-ui</artifactId>
<version>1.0.6</version>
</dependency>
