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

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

實體配置

  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,一方面提高性能,更重要的是安全問題,會把自己的接口暴露出去!!!

?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明:文章內容(如有圖片或視頻亦包括在內)由作者上傳并發布,文章內容僅代表作者本人觀點,簡書系信息發布平臺,僅提供信息存儲服務。