總結之Swagger——SpringBoot集成 Swagger 管理 API 文檔

swagger介紹

官網介紹https://swagger.io/docs/specification/about/

Swagger 是一個規範且完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。

Swagger 的目標是對 REST API 定義一個標準且和語言無關的接口，可以讓人和計算機擁有無須訪問源碼、文檔或網絡流量監測就可以發現和理解服務的能力。當通過 Swagger 進行正確定義，用戶可以理解遠程服務並使用最少實現邏輯與遠程服務進行交互。與爲底層編程所實現的接口類似，Swagger 消除了調用服務時可能會有的猜測。
Swagger 的優勢
支持 API 自動生成同步的在線文檔：使用 Swagger 後可以直接通過代碼生成文檔，不再需要自己手動編寫接口文檔了，對程序員來說非常方便，可以節約寫文檔的時間去學習新技術。
提供 Web 頁面在線測試 API：光有文檔還不夠，Swagger 生成的文檔還支持在線測試。參數和格式都定好了，直接在界面上輸入參數對應的值即可在線測試接口。

一、 項目中集成 Swagger——pom

Pom.xml 添加Maven依賴

!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>

 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
    <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
    </dependency>

二、 Swagger配置文件

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author liuzonghua
 * @Package com.example.rabbitmq_cons_demo.swagger2
 * @Description:
 * @date 2020/4/24 15:28
 */
@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    /**
     * api接口包掃描路徑
     */
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.example.rabbitmq_cons_demo.swagger2.api";

    public static final String VERSION = "1.0.0";

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("1.測試通信")
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any()) // 可以根據url路徑設置哪些請求加入文檔，忽略哪些請求
                .build();
    }
    @Bean
    public Docket socketRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("2.socket通信")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.rabbitmq_cons_demo.swagger2.api"))
                .paths(PathSelectors.any()) // 可以根據url路徑設置哪些請求加入文檔，忽略哪些請求
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("我的Swagger服務") //設置文檔的標題
                .description("我的Swagger服務 API 接口文檔") // 設置文檔的描述
                .version(VERSION) // 設置文檔的版本信息-> 1.0.0 Version information
                .termsOfServiceUrl("http://www.baidu.com") // 設置文檔的License信息->1.3 License information
                .build();
    }
}

三、使用 Swagger 生成文檔

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author liuzonghua
 * @Package com.example.rabbitmq_cons_demo.swagger2.api
 * @Description:
 * @date 2020/4/24 15:53
 */
@RestController
@Api(value = "/apiP", tags = "生產者進程",description = "生產者進程API接口")

@RequestMapping("/apiP")
public class ProducerController {

  @Api(value = "/apiP2", tags = "生產者進程2",description = "生產者進程API接口2")
    @RequestMapping("/sendTest")
    @ResponseBody
    public String sendTest(String text){
        return text;
    }
}

來來來,看看代碼實現了什麼功能

其中一在配置文件中@Bean實現，作爲一個版本
可以配置名稱、包等
其中二在配置文件中@Bean方法中apiInfo實現，文件標題信息等
其三是請求方法，在Controller中@Api和@ApiOperation實現。爲接口信息

@ApiOperation("閘機信息所有列表")
public R list(@RequestParam(required = false) @ApiParam(value = "閘機名稱（搜索使用）") String name,
              @RequestParam(required = false) @ApiParam(value = "景區id") String scenicId) {

頁面強制必填
在後臺採用對象接收參數時，Swagger自帶的工具採用的是JSON傳參， 測試時需要在參數上加入@RequestBody,正常運行採用form或URL提交時候請刪除。

@ApiOperation("監控信息分頁列表")	
@ApiImplicitParam(paramType = "query", dataType = "String", name = "groupId", value = "wifi分組", required = true)
public R list(@RequestParam(required = false) @ApiParam(value = "監控名稱（搜索使用）") String name,
              String groupId,
              @RequestParam(required = false) @ApiParam(value = "當前頁碼,默認1") String pageNum,
              @RequestParam(required = false) @ApiParam(value = "每頁條數，默認10") String pageSize) {

其四是請求參數
也可以是對象

@ApiModel
public class Apple {
    @ApiModelProperty(value = "蘋果id",required = true)
    private String id;
    @ApiModelProperty(value = "蘋果名稱",required = true)
    private String name;
    @ApiModelProperty(value = "蘋果狀態",required = true)
    private int status;

常用註解

• @Api：修飾整個類，描述Controller的作用
• @ApiOperation：描述一個類的一個方法，或者說一個接口
• @ApiParam：單個參數描述
• @ApiModel：用對象來接收參數
• @ApiProperty：用對象接收參數時，描述對象的一個字段
• @ApiResponse：HTTP響應其中1個描述
• @ApiResponses：HTTP響應整體描述
• @ApiIgnore：使用該註解忽略這個API
• @ApiError ：發生錯誤返回的信息
• @ApiImplicitParam：描述一個請求參數，可以配置參數的中文含義，還可以給參數設置默認值
• @ApiImplicitParams：描述由多個 @ApiImplicitParam 註解的參數組成的請求參數列表