Spring Boot 中使用 Swagger

• 2022 年 11 月 5 日
• 筆記
• JAVA, Spring Boot

前後端分離開發，後端需要編寫接⼝說明⽂檔，會耗費⽐較多的時間。
swagger 是⼀個⽤於⽣成伺服器接⼝的規範性⽂檔，並且能夠對接⼝進⾏測試的⼯具。

作用

• ⽣成接⼝說明⽂檔
• 對接⼝進⾏測試

使用步驟

1. 添加依賴

   <!--swagger-->
   <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. 寫配置類 SwaggerConfig

   /**
    * SwaggerConfig 介面文檔配置類
    */
   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
   
       /**
        * 配置介面文檔生成規則
        */
       @Bean
       public Docket getDocket() {
           // 設置文檔生成規則
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo()) // 設置文檔資訊
                   .select()
                   // 設置哪個包下的類需要生成文檔
                  .apis(RequestHandlerSelectors.basePackage("com.luis.fmmall.controller"))
                   .paths(PathSelectors.any()) // 定義哪些路徑的介面需要生成文檔
                   .build();
   
       }
   
       /**
        * 設置文檔資訊
        */
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   .title("xxx介面文檔")
                   .description("這裡是相關描述")
                   .version("1.0")
                   .contact(new Contact("luis",
                           "//www.cnblogs.com/luisblog",
                           "[email protected]"))
                   .build();
       }
   }
   

3. 在控制器類上使用 Swagger 的註解進行相關說明

   示例如下：

   @RestController
   @RequestMapping("/user")
   @Api(tags = "用戶管理", value = "提供用戶的登陸、註冊、修改等功能") //類說明
   public class UserController {
   
       @Resource
       private UserService userService;
   
       @GetMapping("/login")
       @ApiOperation(value = "登陸驗證", notes = "用戶登陸檢查") //方法名說明
       @ApiImplicitParams({ //參數說明
               @ApiImplicitParam(dataType = "string", name = "username", value = "用戶名", required = true),
               @ApiImplicitParam(dataType = "string", name = "password", value = "用戶密碼", required = false, defaultValue = "123")
       })
       public ResultVo login(@RequestParam("username") String name,
                             @RequestParam(value = "password", defaultValue = "123") String pwd) {
           return userService.checkLogin(name, pwd);
       }
   }
   

4. 啟動 SpringBoot 應用，訪問 //localhost:8080/swagger-ui.html

   效果如下：

   

常用註解說明

• @Api：類註解，使用在控制器類上，對類進行說明

  控制器類 UserController 示例：

  @Api(tags = "用戶管理", value = "提供用戶的登陸、註冊、修改等功能") //類說明
  public class UserController {
  }
  

• @ApiOperation：方法註解，使用在方法上，對方法名進行說明

• @ApiImplicitParam 和 @ApiImplicitParams：方法註解，使用在方法上，對方法的形參進行說明

  單個形參使用 @ApiImplicitParam，多個形參使用 @ApiImplicitParams

  控制器類 UserController 的 login 方法示例：

  @GetMapping("/login")
  @ApiOperation(value = "登陸驗證", notes = "用戶登陸檢查") //方法名說明
  @ApiImplicitParams({ //參數說明
      @ApiImplicitParam(dataType = "string", name = "username", value = "用戶名", required = true),
      @ApiImplicitParam(dataType = "string", name = "password", value = "用戶密碼", required = false, defaultValue = "123")
  })
  public ResultVo login(@RequestParam("username") String name,
                        @RequestParam(value = "password", defaultValue = "123") String pwd) {
      return userService.checkLogin(name, pwd);
  }
  

• @ApiModel 和 @ApiModelProperty：當接⼝的形參或返回值為對象類型時，在實體類中添加此註解說明

  介面的返回值為 ResultVo 對象示例：

  @Data
  @NoArgsConstructor
  @AllArgsConstructor
  @ApiModel(value = "ResultVo 對象", description = "返回給前端的封裝數據") //返回的類說明
  public class ResultVo {
  
      // 響應給前端的狀態碼
      @ApiModelProperty("響應狀態碼") //屬性說明
      private int code;
  
      // 響應給前端的提示資訊
      @ApiModelProperty("提示資訊") //屬性說明
      private String msg;
  
      // 響應給前端的數據
      @ApiModelProperty("數據") //屬性說明
      private Object data;
  }
  

  介面的形參為 User 實體對象示例：

  @Data
  @NoArgsConstructor
  @AllArgsConstructor
  @ApiModel(value = "User 對象",description = "⽤戶/買家資訊")
  public class User {
  	@ApiModelProperty(dataType = "int",required = false)
      private int userId;
      @ApiModelProperty(dataType = "String",required = true, value = "⽤
      戶註冊帳號")
      private String userName;
      @ApiModelProperty(dataType = "String",required = true, value = "⽤
      戶註冊密碼")
      private String userPwd;
      @ApiModelProperty(dataType = "String",required = true, value = "⽤
      戶真實姓名")
      private String userRealname;
      @ApiModelProperty(dataType = "String",required = true, value = "⽤
      戶頭像url")
      private String userImg;
  }
  

• @ApiIgnore：接⼝⽅法註解，添加此註解的⽅法將不會⽣成到接⼝⽂檔中

swagger-ui 插件

發現一個規律，越學到最後，越是有驚喜，有不有？

swagger-ui 插件是一款 UI 美化插件，是基於 swagger 的。

之前使用的默認 swagger 文檔和調試頁面如果使用起來不太順暢，可以試試這款 swagger-ui 插件。

使用

1. 添加依賴

   <dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>swagger-bootstrap-ui</artifactId>
       <version>1.9.6</version>
   </dependency>
   

2. 重啟 SpringBoot 應用，訪問 //localhost:8080/doc.html

   效果如下：

   

   

   

還等什麼，趕緊裝插件去~