Swagger 的介紹以及使用
本文代碼已經同步到碼云 ,歡迎大家 star https://gitee.com/njitzyd/JavaDemoCollection
Swagger 簡介
Swagger 是一個主要用來在線生成文檔的插件,這里主要用來動態生成api接口供前后端進行交互,如果不生成的話就需要寫靜態文檔來交互,那樣不僅很慢而且不容易修改,那Swagger就可以解決這個問題。
- 號稱世界上最流行的API框架
- Restful Api 文檔在線自動生成器 => API 文檔 與API 定義同步更新
- 直接運行,在線測試API
- 支持多種語言 (如:Java,PHP等)
- 官網:https://swagger.io/
swagger 的使用(基于SpringBoot)
1.引入依賴
新建一個SpringBoot 項目,只加入 web 的啟動器,然后添加下面兩個依賴:
<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>
2.創建一個DemoController
@RestController
public class DemoController {
/**
*
* @description: 注意這種寫法Swagger 會生成很多個接口(雖然參數里指定了GET,Swagger掃描不到)
* 所以在實際的開發中盡量使用 @GetMapping 等這種指定了方法的方式
* @param: []
* @return: java.lang.String
* @date: 2020/8/2
*/
@RequestMapping(value = "index",method = RequestMethod.GET)
public String hello(){
return "helloWorld";
}
}
3.創建Swagger 的配置類
@Configuration //配置類
@EnableSwagger2// 開啟Swagger2的自動配置
public class SwaggerConfig {
}
4.啟動項目
訪問地址:http://localhost:8080/swagger-ui.html,可以看到Swagger 的頁面:
image-20200802175756924
Swagger 的配置
剛剛啟動后,頁面的內容都是默認的,在實際使用中需要我們進行配置。
配置Swagger 掃描的接口
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通過.select()方法,去配置掃描接口,RequestHandlerSelectors配置如何掃描接口
.apis(RequestHandlerSelectors.basePackage("com.njit.swagger.controller"))
.build();
}
其中RequestHandlerSelectors 有很多可以配置的方法,具體如下,可以根據自己的項目選擇:
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) // 根據包路徑掃描接口
除此之外,我們還可以通過.paths
配置接口掃描過濾:
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通過.select()方法,去配置掃描接口,RequestHandlerSelectors配置如何掃描接口
.apis(RequestHandlerSelectors.basePackage("com.njit.swagger.controller"))
// 配置如何通過path過濾,即這里只掃描請求以/kuang開頭的接口
.paths(PathSelectors.ant("/njit/**"))
.build();
}
PathSelectors 也是可以多種配置的:
any() // 任何請求都掃描
none() // 任何請求都不掃描
regex(final String pathRegex) // 通過正則表達式控制
ant(final String antPattern) // 通過ant()控制
配置Swagger 的開關
通過enable()方法配置是否啟用swagger,如果是false,swagger將不能在瀏覽器中訪問了
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false) //配置是否啟用Swagger,如果是false,在瀏覽器將無法訪問
.select()// 通過.select()方法,去配置掃描接口,RequestHandlerSelectors配置如何掃描接口
.apis(RequestHandlerSelectors.basePackage("com.njit.swagger.controller"))
// 配置如何通過path過濾,即這里只掃描請求以/njit開頭的接口
.paths(PathSelectors.ant("/njit/**"))
.build();
}
動態配置當項目處于test、dev環境時顯示swagger,否則不顯示
首先在application.properties 中配置激活的配合環境,然后再做如下配置:
@Bean
public Docket docket(Environment environment) {
// 設置要顯示swagger的環境
Profiles of = Profiles.of("dev", "test");
// 判斷當前是否處于該環境
// 通過 enable() 接收此參數判斷是否要顯示
boolean flag = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag) //配置是否啟用Swagger,如果是false,在瀏覽器將無法訪問
.select()// 通過.select()方法,去配置掃描接口,RequestHandlerSelectors配置如何掃描接口
.apis(RequestHandlerSelectors.basePackage("com.njit.swagger.controller"))
// 配置如何通過path過濾,即這里只掃描請求以/njit開頭的接口
//.paths(PathSelectors.ant("/njit/**"))
.build();
}
配置API分組
很簡單只要配置groupName()即可,如果想要配置多個分組,name就配多個Docket實例,注意實例的名稱不能重復。
@Bean
public Docket docket(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.groupName("hello") // 配置分組
// 省略配置....
}
配置多個分組
@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");
}
實體配置
- 新建一個實體類可以在上面使用注解(注意,如果接口中的返回值中有實體類,name實體類就會自動被識別為model,無論你加不加注解,當然加注解后會顯示你加的注解,比較詳細)
// @ApiModel為類添加注釋
// @ApiModelProperty為類屬性添加注釋
@ApiModel("用戶實體")
public class User {
@ApiModelProperty("用戶名")
public String username;
@ApiModelProperty("密碼")
public String password;
}
常用注解
Swagger注解 | 簡單說明 |
---|---|
@Api(tags = "xxx模塊說明") | 作用在模塊類上 |
@ApiOperation("xxx接口說明") | 作用在接口方法上 |
@ApiModel("xxxPOJO說明") | 作用在模型類上:如VO、BO |
@ApiModelProperty(value = "xxx屬性說明",hidden = true) | 作用在類方法和屬性上,hidden設置為true可以隱藏該屬性 |
@ApiParam("xxx參數說明") | 作用在參數、方法和字段上,類似@ApiModelProperty |
這樣就可以在controller類以及方法以及參數中使用相應的注解來完善我們的Swagger,特別說明的是,在生產環境中一定要關閉Swagger,一方面提高性能,更重要的是安全問題,會把自己的接口暴露出去!!!