Spring-Boot快速集成Swagger插件（Api在線接口文檔）

關於Swagger

Swagger 是一個規範且完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。
Swagger 的目標是對 REST API 定義一個標準且和語言無關的接口，可以讓人和計算機擁有無須訪問源碼、文檔或網絡流量監測就可以發現和理解服務的能力。當通過 Swagger 進行正確定義，用戶可以理解遠程服務並使用最少實現邏輯與遠程服務進行交互。與爲底層編程所實現的接口類似，Swagger 消除了調用服務時可能會有的猜測

當存在一個RESTful 的項目，需要和別人對接時，爲了方便閱讀的你提供的接口。引入Swagger後，關於輸入參數、返回參數和請求方式，都可以清晰的看見。方便api文檔的管理，同時需要的話還可以作爲api的測試工具。

Spring-Boot集成Swagger

1.添加依賴

        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.5.0</version>
        </dependency>
        <!-- swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.5.0</version>
        </dependency>

2.Swagger配置

這裏我使用的配置類和yml配置文件去整合的

yml配置

# swagger config
com.dl.demo.plugin.swagger:
   enable: true
   scan.package: com.dl.demo.controller

配置類

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${com.dl.demo.plugin.swagger.enable}")
    private boolean swaggerEnable;

    @Value("${com.dl.demo.plugin.swagger.scan.package}")
    private String scanPackage;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnable)
                .apiInfo(apiInfo())
                .select()
                //爲當前包路徑
                .apis(RequestHandlerSelectors.basePackage(scanPackage))
                .paths(PathSelectors.any())
                .build();
    }
    //構建 api文檔的詳細信息函數,注意這裏的註解引用的是哪個
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //頁面標題
                .title("Demo項目API一覽")
                //創建人
                .contact(new Contact("DavidLei08", "https://github.com/DavidLei08/", "[email protected]"))
                //版本號
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }

}

爲了方便再不同環境下切換配置，我將swagger的enable和掃描包的配置抽出在ym配置文件中。
當需要禁用swagger時只需要將enable改成false,掃描包名可以根據實際情況修改。

3.controller層使用

@Api 標註當前controller類爲api模塊
@ApiOperation 標註當前方法爲api接口
@ApiResponse 標註當前方法的響應狀態和message信息
@ApiParam 標註當前方法的入力參數dto

/**
 * MqSendController
 * @author  DavidLei08
 */
@Api(value = "用戶管理類")
@RestController
public class MqSendController {

    @Autowired
    private MqOperationService mqOperationService;


    @ApiOperation(value = "發送mq")
    @PostMapping("/sendmq")
    @ApiResponse(code = 200, message = "發送mq請求返回的dto")
    public BaseResponse sendMq(@ApiParam  @Valid  @RequestBody MqSendRequest request,
                               BindingResult result, HttpServletResponse httpResponse){
        BaseResponse response = new BaseResponse();
        if(!result.hasErrors()){
            try {
                mqOperationService.sendMq(request);
                response.setHttpStatus("200");
                response.setMessage("request is ok");
            } catch (Exception e){
                httpResponse.setStatus(500);
                response.setHttpStatus("500");
                response.setMessage("mq send failed");
            }
        } else {
            httpResponse.setStatus(401);
            response.setHttpStatus("401");
            response.setMessage("request formatter is wrong");
        }
        return  response;
    }

}

關於api的文檔，可能需要顯示，也可能不需要顯示，比如error統一處理的controller就不需要對外暴露。
可以將 @Api 替換成 @ApiIgnore 表示api文檔忽略當前類。當前類就不會出現再api文檔中。

/**
 * MqSendController
 * @author  DavidLei08
 */
@ApiIgnore
//@Api(value = "用戶管理類")
@RestController
public class MqSendController {

    @Autowired
    private MqOperationService mqOperationService;


    @ApiOperation(value = "發送mq")
    @PostMapping("/sendmq")
    @ApiResponse(code = 200, message = "發送mq請求返回的dto")
    public BaseResponse sendMq(@ApiParam  @Valid  @RequestBody MqSendRequest request,
                               BindingResult result, HttpServletResponse httpResponse){
        BaseResponse response = new BaseResponse();
        if(!result.hasErrors()){
            try {
                mqOperationService.sendMq(request);
                response.setHttpStatus("200");
                response.setMessage("request is ok");
            } catch (Exception e){
                httpResponse.setStatus(500);
                response.setHttpStatus("500");
                response.setMessage("mq send failed");
            }
        } else {
            httpResponse.setStatus(401);
            response.setHttpStatus("401");
            response.setMessage("request formatter is wrong");
        }
        return  response;
    }

}

4.輸入dto使用

@ApiModel 表示當前類爲api輸入的model
@ApiModelProperty 表示當前字段爲輸入字段 -value 是解釋 -example 是例子 -required 表示是否是必須字段

/**
 * MqSendRequest
 * @author DavidLei08
 */
@ApiModel(value = "mq發送傳入信息model")
public class MqSendRequest implements Serializable {

    @NotNull
    @NotEmpty
    @ApiModelProperty(value = "mq類型-topic/queue", example = "topic",required = true)
    private String mqType;

    @NotNull
    @NotEmpty
    @ApiModelProperty(value = "發送目的地名", example = "float_01",required = true)
    private String toName;

    @NotNull
    @NotEmpty
    @ApiModelProperty(value = "發送信息內容", example = "test message",required = true)
    private String message;

    public String getMqType() {
        return mqType;
    }

    public void setMqType(String mqType) {
        this.mqType = mqType;
    }

    public String getToName() {
        return toName;
    }

    public void setToName(String toName) {
        this.toName = toName;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

swagger插件真心不錯
不過代碼中會多很多註解，看起來內容有點多，其實無關乎業務，哈哈!!