SpringBoot結合Swagger2生產環境實踐

網絡上有很多swagger的博客,往往都是複製來複制去,隨便粘幾個api,遺失了很多實際應用中必要的元素,不滿足實際生產環境需要.下面分享出我的最佳實踐,供大家參考.轉載請註明出處.

swagger介紹

swagger是一個開源免費的後端接口文檔解決方案, 可以通過全註解方式實現註釋. 簡化前後端溝通成本, 提供生成詳細文檔, 接口請求測試等能力. Swagger官方網站

應用場景

1. 前後端分離項目
2. 向接口調用方實現全面的接口路徑,請求參數,返回結果等註釋信息
3. 讓接口調用方方便高效的模擬訪問接口
4. 後臺開發通過全註解形式編寫註釋信息,無需多餘的xml, json配置
5. 爲項目提供統一的返回格式規範

SpringBoot2.x整合Swagger2

引入Maven依賴
此處Swagger2採用2.9.2版本, Swagger2.6.1版本存在bug, 當controller的tag註釋爲中文時,點擊controller無法展開方法列表

		<!--swagger2後臺邏輯依賴-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
       	<!--swagger2可視化界面依賴-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

添加Swagger2基本配置

@Configuration
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
        		// 獲取項目基本信息
                .apiInfo(apiInfo())
                // 獲得api選擇器builder
                .select()
                // 只掃描類上面有@RestController註解的類包含的接口
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                // 包含任何路徑接口
                .paths(PathSelectors.any())
                .build();
    }
	// 提供項目基本信息, 內容會顯示在Swagger2可視化界面中
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
        		// 文檔首頁標題
                .title("api-manager文檔")
                // 文檔整體描述
                .description("華宇接口運維管理平臺接口文檔")
                // 文檔版本
                .version("1.0")
                .build();
    }
}

至此,我們便完成了Swagger2與SpringBoot2.x的整合.啓動項目, 訪問項目地址/swagger-ui.html可以看到下圖界面.

項目返回數據結構

項目返回數據結構大同小異, 三個必備元素爲

1. code 標識業務狀態是否成功
2. msg 業務提示信息
3. data 接口實際返回數據

這裏唯一需要注意的地方是data字段採用泛型T而不是Object來存儲, 這樣設計可以讓Swagger明確的展示返回結果註釋具體代碼如下, 暫時無需關注Api開頭的註解, Swagger常用註解後面會說到.

@ApiModel(value = "com.thunisoft.apimanager.util.CommonResult", description = "接口通用返回結果結構")
@Data
public final class CommonResult<T> {
    @ApiModelProperty(value = "1成功, 其他code值均爲失敗")
    private Integer code;
    @ApiModelProperty(value = "提示信息")
    private String msg;
    @ApiModelProperty(value = "返回結果實際數據")
    private T data;
}

返回結果工具類

光有統一的返回結果是不夠的, 我們再加入一個輔助生成結果的工具類.其中SysCodeEnum爲項目內管理返回值和描述的枚舉類, 不展開描述, 工具類中我們同樣採用了泛型參數, 讓返回結果用友明確的具體類型.

public class ResultUtil {
    public static <T> CommonResult<T> renderFailure(SysCodeEnum code, T data) {
        CommonResult<T> result = new CommonResult<>();
        result.setCode(code.getCode());
        result.setData(data);
        result.setMsg(code.getDescription());
        return result;
    }

    public static CommonResult renderFailure(String msg) {
        CommonResult result = new CommonResult();
        result.setCode(SysCodeEnum.FAILURE.getCode());
        result.setData(null);
        result.setMsg(msg);
        return result;
    }

    public static CommonResult renderSuccess() {
        CommonResult result = new CommonResult();
        result.setCode(SysCodeEnum.SUCCESS.getCode());
        result.setMsg(SysCodeEnum.SUCCESS.getDescription());
        return result;
    }

    public static CommonResult renderSuccess(String msg) {
        CommonResult result = new CommonResult();
        result.setCode(SysCodeEnum.SUCCESS.getCode());
        result.setMsg(msg);
        return result;
    }

    public static <T> CommonResult<T> renderSuccess(T data) {
        CommonResult<T> result = new CommonResult<>();
        result.setCode(SysCodeEnum.SUCCESS.getCode());
        result.setMsg(SysCodeEnum.SUCCESS.getDescription());
        result.setData(data);
        return result;
    }

    public static <T> CommonResult<T> renderSuccess(String msg, T data) {
        CommonResult<T> result = new CommonResult<>();
        result.setCode(SysCodeEnum.SUCCESS.getCode());
        result.setMsg(msg);
        result.setData(data);
        return result;
    }
}

Swagger常用註解

Swagger常用註解主要分爲兩類,一類是Controller層使用的註解, 另一類是Model中使用的註解.
Controller層常用的註解有@Api, @ApiOperation, @ApiParam三個.具體含義以及示例代碼如下:

@Api(tags = {"接口信息配置相關"}) // 註釋Contr作用, 會顯示在Swagger首頁的Controller列表中
@RestController
@RequestMapping("/manager")
public class ApiManagerController {
    @Autowired
    private ApiManagerService apiManagerService;

    @ApiOperation(value = "添加接口信息", notes = "添加接口信息")// 接口註釋,value顯示在接口列表, notes顯示在接口詳細內容
    @PostMapping("/add")
    public CommonResult addApiManager(@ApiParam(value = "接口信息參數", required = true) @Validated({InsertGroup.class}) // @ApiParam提供了參數總體描述
                                          @RequestBody ApiManagerDTO apiManagerDTO) {
        apiManagerService.addApiManager(apiManagerDTO);
        return ResultUtil.renderSuccess();
    }
}

Model註解提供了請求參數與返回結果的註釋能力,常用註解有@ApiModel, @ApiModelProperty, 下面只給出請求參數Model ApiManagerDTO的示例代碼, 返回結果Model註釋方式相同.

@ApiModel(value = "com.thunisoft.apimanager.pojo.dto.ApiManagerDTO", description = "添加api接口信息參數")
// @ApiModel制定了class路徑與描述
@Data
public class ApiManagerDTO {
    @ApiModelProperty(value = "接口名", required = true) // @ApiModelProperty指定了接口中文含義以及是否必傳
    private String apiName;
    @ApiModelProperty(value = "接口狀態0關閉, 1開啓", required = true, allowableValues = "0, 1")
    // @ApiModelProperty中allowableValues註釋了該字段允許傳遞哪些值
    private Integer apiStatus;
}

實際效果

至此, 我們只使用了5個Swagger的基本註解就完成了應用場景中5個需求,從此後臺開發擺脫了單獨編寫接口文檔文件的束縛.簡單接口冒煙甚至不再需要Postman.實際效果如下: