Swagger 的介紹以及使用

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 的頁面：

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");
}

實體配置

1. 新建一個實體類能夠在上面使用註解（注意，若是接口中的返回值中有實體類，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，一方面提升性能，更重要的是安全問題，會把本身的接口暴露出去！！！