SpringBoot集成Swagger2

SpringBoot集成Swagger2

本文注重實踐，理論介紹可自行google。本文將從Swagger2的集成開始，逐步完成一個具有高度參考價值的API文檔。

參考資料

• Swagger官方文檔:鏈接

集成Swagger2

SpringBoot繼承Swagger2

• 創建SpringBoot項目
  不重複介紹，可參考使用IDEA創建SpringBoot項目
• 引入swagger2依賴

  //Swagger
    implementation 'io.springfox:springfox-swagger2:2.9.2'
    implementation 'io.springfox:springfox-swagger-ui:2.9.2'

    //另外項目中會用到lombok所以這裏也引入依賴
    //lombok插件，這裏採用官方推薦的方式，防止gradle build時找不到lombok
    annotationProcessor 'org.projectlombok:lombok:1.18.2'
    compileOnly 'org.projectlombok:lombok:1.18.2'
    testAnnotationProcessor 'org.projectlombok:lombok:1.18.2'
    testCompileOnly 'org.projectlombok:lombok:1.18.2'

• Swagger配置
  • 在啓動類添加註解@EnableSwagger2,啓用swagger2
  • 編寫配置類

  @Configuration
public class Swagger2Config {
    @Bean
    public Docket adminsApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.virtuex"))
                .build()
                .groupName("apis")
                ;
    }
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("xxxx系統接口說明")
               .description("測試使用")
                .version("v1.0")
                .build();
    }
}

一個簡單的demo

這裏隨便寫個controller來測試下頁面顯示的效果，具體代碼不貼了，可在最後的github倉庫上查看，訪問http://127.0.0.1:8880/swagger-ui.html效果如下：

這裏可以看到系統的接口，代碼中寫了兩個controller，如下：

@Api("認證與授權")
@RestController
public class AuthController {

@RestController
@ApiIgnore
public class UserController {

第二個使用了@ApiIgnore，這個註解會跳過這個controller。所以頁面上沒有顯示。
但是這只是簡單的接口名稱以及一些狀態碼，參考價值並不大，下面將就這些接口細化下顯示的內容，使其具有更大的參考價值。

細化接口內容

增加接口描述

一份具有高度參考價值的文檔，必須要有直觀、詳細的描述。其中需要描述接口的作用，描述輸入輸出參數的作用等，下面就此進行完善

• 使用@Api註解爲類添加說明

@RestController
@Api("用戶管理")
public class UserController {

• 使用@ApiOperation給方法添加描述

    @ApiOperation("添加用戶")
    @PostMapping("/add")
    public String addAdmin(@RequestBody User user){
        return "OK";
    }
}

• User類定義如下：

@Data
@Component
@ApiModel(value = "User", description = "用戶實體類")
public class User implements Serializable {
    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "用戶ID")
    private Integer userId;

    @ApiModelProperty(value = "用戶名" , example = "張三")
    private int username;

    @ApiModelProperty(value = "密碼")
    private String password;

}

這裏需要注意的是：

• 1. Model與Swagger集成需要在對應的controller中加入@RequestBody註解，否則Swagger不顯示Model且不報錯
• 2. 如果結合lombok需要有@ Data註解（否則就要有getter/setter）,否則swagger上不顯示字段信

• 啓動項目，看下效果
  
  從圖中可以看到，請求參數中需要User實體，具體的User各字段和實例也可以看到，這樣就稍微有了點參考的用途。

使用Model格式化輸入輸出

以新增用戶的相應爲例，新增下面的model作爲相應響應結構：

@Data
@ApiModel(value = "AddDataResponse", description = "響應實體")
public class AddDataResponse {
    @ApiModelProperty(value = "數據主鍵值" , example = "1")
    private Integer dataRid;
    @ApiModelProperty(value = "響應狀態碼" , example = "200")
    private Integer code;
    @ApiModelProperty(value = "描述" , example = "創建成功")
    private String desc;
}

在對應的controller方法上配置響應結構：

  @ApiOperation("添加用戶")
    @PostMapping("/add")
    @ApiResponses({@ApiResponse(code = 200, response = AddDataResponse.class, message = "成功")})
    public String addAdmin(@RequestBody User user){
        return "OK";
    }

啓動項目，進入swagger-ui頁面

從圖中可以看出，新增的響應內容顯示在了頁面上。

指定相應狀態碼及結構

從上一例中看出，可以指定多個響應，並且每個狀態碼都有具體的響應結構。接下來就以200，401，403爲例來進行封裝。

• 200結構體與上一例相同
• 401結構體

@Data
@ApiModel(value = "Response401", description = "401響應實體")
public class Response401 {
    @ApiModelProperty(value = "業務ID" , example = "12345678")
    private Long bizId;
    @ApiModelProperty(value = "描述" , example = "未認證")
    private String message;
    @ApiModelProperty(value = "建議" , example = "請先認證")
    private String suggestion;
}

• 403結構體

@Data
@ApiModel(value = "Response403", description = "403響應實體")
public class Response403 {
    @ApiModelProperty(value = "業務ID" , example = "123564")
    private Long bizId;
    @ApiModelProperty(value = "描述" , example = "禁止訪問")
    private String message;
    @ApiModelProperty(value = "建議" , example = "請確認是否有權限訪問")
    private String suggestion;
}

• 添加至對應接口

  @ApiOperation("添加用戶")
    @PostMapping("/add")
    @ApiResponses({@ApiResponse(code = 200, response = AddDataResponse.class, message = "成功"),
            @ApiResponse(code = 401, response = Response401.class, message = "未認證"),
            @ApiResponse(code = 403, response = Response403.class, message = "禁止訪問")
    })
    public String addAdmin(@RequestBody User user){
        return "OK";
    }

• 啓動服務，並訪問swagger頁面，結果如下：

抽象出通用Model

根據前幾例中的響應Model，每個響應都有一個業務ID，所以這個Id我們可以抽象出一個BaseModel

@Data
public abstract class BaseModel {
    @ApiModelProperty(value = "業務流水號" , example = "123-454-845-454")
    private String bizId;
}

其他Model繼承自此Model

public class Response401 extends BaseModel {

    @ApiModelProperty(value = "描述" , example = "未認證")
    private String message;
    @ApiModelProperty(value = "建議" , example = "請先認證")
    private String suggestion;
}

啓動項目，訪問UI界面

接口分組管理

實例中只有一個Controller，所以在頁面顯示佈局不會很擁擠。一旦controller多了，全擠在一個頁面，那就顯得很亂。這時可以通過新建Docket來指定分組。如，增加Oauth和自定義的auth兩個接口組

    @Bean
    public Docket authApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.ant("/auth/**"))
                .build()
                .groupName("auth_api")
                ;
    }

    @Bean
    public Docket oauthApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.ant("/oauth/**"))
                .build()
                .groupName("oauth_api")
                ;
    }

啓動項目，訪問頁面:

這樣切換分組就能看到不同的接口

美化界面

推薦一個開源項目，項目倉庫可點擊跳轉，效果圖如下：

接口規範

• Google Rest Api規範
• Github Rest接口

項目代碼

github地址