Spring Boot 中使用 Swagger

前後端分離開發，後端需要編寫接⼝說明⽂檔，會耗費⽐較多的時間。

swagger 是⼀個⽤于⽣成伺服器接⼝的規範性⽂檔，并且能夠對接⼝進⾏測試的⼯具。

作用

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

使用步驟

1. 添加依賴

<code-box id="code-86ShJR" style="padding: 0px; margin: 5px; position: relative; display: block; border-radius: 4px; box-shadow: rgba(37, 44, 97, 0.15) 0px 4px 11px -2px, rgba(93, 100, 148, 0.06) 0px 1px 3px 0px;">```
    <!--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>      

1. 寫配置類 ​

   ​SwaggerConfig​

   ​

<code-box id="code-WSwFJh" style="padding: 0px; margin: 5px; position: relative; display: block; border-radius: 4px; box-shadow: rgba(37, 44, 97, 0.15) 0px 4px 11px -2px, rgba(93, 100, 148, 0.06) 0px 1px 3px 0px;">```
    /**
     * 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",
                            "https://www.cnblogs.com/luisblog",
                            "[email protected]"))
                    .build();
        }
    }      

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

   示例如下：

<code-box id="code-TC7SGH" style="padding: 0px; margin: 5px; position: relative; display: block; border-radius: 4px; box-shadow: rgba(37, 44, 97, 0.15) 0px 4px 11px -2px, rgba(93, 100, 148, 0.06) 0px 1px 3px 0px;">```
    @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);
        }
    }      

1. 啟動 SpringBoot 應用，通路 ​

   ​http://localhost:8080/swagger-ui.html​

   ​

常用注解說明

• ​

  ​@Api​

  ​：類注解，使用在控制器類上，對類進行說明

  控制器類 UserController 示例：

<code-box id="code-pwhHNp" style="padding: 0px; margin: 5px; position: relative; display: block; border-radius: 4px; box-shadow: rgba(37, 44, 97, 0.15) 0px 4px 11px -2px, rgba(93, 100, 148, 0.06) 0px 1px 3px 0px;">```
    @Api(tags = "使用者管理", value = "提供使用者的登陸、注冊、修改等功能") //類說明
    public class UserController {
    }      

• ​

  ​@ApiOperation​

  ​：方法注解，使用在方法上，對方法名進行說明
• ​

  ​@ApiImplicitParam​

  ​ 和 

  @ApiImplicitParams

  ：方法注解，使用在方法上，對方法的形參進行說明

  單個形參使用 

  @ApiImplicitParam

  ，多個形參使用 

  @ApiImplicitParams

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

<code-box id="code-CytCJ5" style="padding: 0px; margin: 5px; position: relative; display: block; border-radius: 4px; box-shadow: rgba(37, 44, 97, 0.15) 0px 4px 11px -2px, rgba(93, 100, 148, 0.06) 0px 1px 3px 0px;">```
    @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 對象示例：

<code-box id="code-kCHXrG" style="padding: 0px; margin: 5px; position: relative; display: block; border-radius: 4px; box-shadow: rgba(37, 44, 97, 0.15) 0px 4px 11px -2px, rgba(93, 100, 148, 0.06) 0px 1px 3px 0px;">```
    @Data
    @NoArgsConstructor
    @AllArgsConstructor
    @ApiModel(value = "ResultVo 對象", description = "傳回給前端的封裝資料") //傳回的類說明
    public class ResultVo {

        // 響應給前端的狀态碼
        @ApiModelProperty("響應狀态碼") //屬性說明
        private int code;

        // 響應給前端的提示資訊
        @ApiModelProperty("提示資訊") //屬性說明
        private String msg;

        // 響應給前端的資料
        @ApiModelProperty("資料") //屬性說明
        private Object data;
    }      

接口的形參為 User 實體對象示例：      

<code-box id="code-JXzm6p" style="padding: 0px; margin: 5px; position: relative; display: block; border-radius: 4px; box-shadow: rgba(37, 44, 97, 0.15) 0px 4px 11px -2px, rgba(93, 100, 148, 0.06) 0px 1px 3px 0px;">```
    @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 插件

使用

1. 添加依賴

<code-box id="code-tBr8zQ" style="padding: 0px; margin: 5px; position: relative; display: block; border-radius: 4px; box-shadow: rgba(37, 44, 97, 0.15) 0px 4px 11px -2px, rgba(93, 100, 148, 0.06) 0px 1px 3px 0px;">```
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>swagger-bootstrap-ui</artifactId>
        <version>1.9.6</version>
    </dependency>      

1. 重新開機 SpringBoot 應用，通路 ​

   ​http://localhost:8080/doc.html​

   ​