swagger 基礎用法全解析

語言: CN / TW / HK

swagger 基礎用法全解析

Swagger 是一個規範和完整的框架,用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。總體目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法,引數和模型緊密整合到伺服器端的程式碼,允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。

maven依賴


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

其中版本號視具體而定。

建立swagger配置類


package com.swaggerTest;
 
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;
 
/**
 * Swagger2配置類
 * 在與spring boot整合時,放在與Application.java同級的目錄下。
 * 通過@Configuration註解,讓Spring來載入該類配置。
 * 再通過@EnableSwagger2註解來啟用Swagger2。
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    
    /**
     * 建立API應用
     * apiInfo() 增加API相關資訊
     * 通過select()函式返回一個ApiSelectorBuilder例項,用來控制哪些介面暴露給Swagger來展現,
     * 本例採用指定掃描的包路徑來定義指定要建立API的目錄。
     * 
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swaggerTest.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    /**
     * 建立該API的基本資訊(這些基本資訊會展現在文件頁面中)
     * 訪問地址:http://專案實際地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構建RESTful APIs")
                .description("Swagger構建演示")
                .termsOfServiceUrl("")
                .contact("sunf")
                .version("1.0")
                .build();
    }
}

swagger的註解說明

Swagger使用的註解及其說明:

@Api:用在類上,說明該類的作用。

@ApiOperation:註解來給API增加方法說明。

@ApiImplicitParams : 用在方法上包含一組引數說明。

@ApiImplicitParam:用來註解來給方法入參增加說明。

@ApiResponses:用於表示一組響應

@ApiResponse:用在@ApiResponses中,一般用於表達一個錯誤的響應資訊

   code:數字,例如400

   message:資訊,例如"請求引數沒填好"

   response:丟擲異常的類   

@ApiModel:描述一個Model的資訊(一般用在請求引數無法使用@ApiImplicitParam註解進行描述的時候)

   @ApiModelProperty:描述一個model的屬性

其中每個註解的具體作用以及屬性還可以通過檢視原始碼的註釋。

swagger 註解的使用

1. 整個類的說明

使用@Api,參考如下:


@Api(value = "ApiObjMapController, api配置對映物件資訊控制類")
@Controller
@RequestMapping("/api/v1.0.0/apiObjMap")
public class ApiObjMapController {
}

2. 單個引數

方法使用@ApiOperation註解,單個引數直接使用@ApiImplicitParam,參考如下:


@ApiOperation(value = "根據id刪除api配置對映物件", notes = "id必傳。")
    @ApiImplicitParam(paramType = "query", name = "id", value = "主鍵id", required = true, dataType = "String")
    @RequestMapping(value = "/deleteApiObjMap", method = RequestMethod.GET)
    @ResponseBody
    public R deleteApiObjMap(@RequestParam("id") String id) {
    }

3. 多個傳參

多個引數可以使用使用@ApiImplicitParams搭配@ApiImplicitParam使用,示例如下:


@ApiOperation("api配置對映物件分頁查詢介面")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "pageNumber", value = "頁碼", defaultValue = "1", required = true, dataType = "int"),
            @ApiImplicitParam(paramType = "query", name = "pageSize", value = "每頁個數", defaultValue = "10", required = true, dataType = "int"),
            @ApiImplicitParam(paramType = "query", name = "dsName", value = "資料來源名稱", dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "collectType", value = "採集型別", dataType = "String")
    })
    @RequestMapping(value = "/getPageInfo", method = RequestMethod.GET)
    @ResponseBody
    public R getPageInfo(@RequestParam(value = "pageNumber", defaultValue = "1") int pageNumber,
            @RequestParam(value = "pageSize", defaultValue = "10") int pageSize,
            @RequestParam(value = "dsName", required = false) String dsName,
            @RequestParam(value = "collectType", required = false) String collectType) {
            }

4. 當傳入引數是物件的時候

controller層程式碼如下:


 @ApiOperation("儲存api配置對映物件")
    @RequestMapping(value = "/updateApiObjMap", method = RequestMethod.POST)
    @ResponseBody
    public R updateApiObjMap(@RequestBody @Valid ApiObjMap apiObjMap) {
    }
    

直接在傳入的物件對應的類程式碼上面使用@ApiModel (模型)和 @ApiModelProperty(具體屬性),示例如下:



@ApiModel(value = "api物件對映配置類")
public class ApiObjMap {

    @ApiModelProperty(value = "主鍵")
    private String apiObjMapId;

    @ApiModelProperty(value = "資料來源名稱", required = true)
    @NotBlank(message = "資料來源名稱不能為空!")
    private String dsName;

    @ApiModelProperty(value = "採集型別", required = true)
    @NotBlank(message = "採集型別不能為空!")
    private String collectType;

    @ApiModelProperty(value = "我們的欄位名稱", required = true)
    @NotEmpty
    private String ourCol;

    @ApiModelProperty(value = "api的欄位名稱", required = true)
    @NotEmpty
    private String apiCol;

    @ApiModelProperty(value = "指定值")
    private String specificVal;

    @ApiModelProperty(value = "對應含義")
    private String meaning;

    @ApiModelProperty(value = "資料型別", required = true)
    @NotEmpty
    private String dataType;

    @ApiModelProperty(value = "建立時間", hidden = true)
    private Date createTime;

    @ApiModelProperty(value = "更新時間", hidden = true)
    private Date updateTime;
    
    // 省略get和set方法
    }

對於用到@ApiModelProperty具體屬性的說明:

  1. value: 屬性含義說明
  2. required: 是否為必須引數
  3. hidden: 是否隱藏,如果true的話,前端顯示該類的時候會隱藏該欄位。

這幾個基本也是最常用的幾個了。

5. 當傳參物件為List巢狀物件時

controller層程式碼如下:


@ApiOperation("儲存api配置對映物件list")
    @RequestMapping(value = "/saveList", method = RequestMethod.POST)
    @ResponseBody
    public R saveList(@RequestBody @Valid ApiObjMapList list) {
    }

直接在ApiObjMapList使用相關注解,並且巢狀物件ApiObjMap也使用了swagger的文件說明,具體內容同上面第4點。


@ApiModel(value = "api物件對映配置list模型")
@Data
public class ApiObjMapList {

    @ApiModelProperty(value = "api物件對映配置列表", dataType = "list")
    @Valid
    List<ApiObjMap> list;

}

其中@ApiModelProperty還使用了屬性dataType = "list",說明型別為列表。這樣就可以巢狀展示物件具體內容了,對於多個類巢狀的情況,這種方式應該都可用(小編目前沒試過多個層層巢狀的)。

swagger前端

前端地址:

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

訪問該地址即可檢視你自己定義的介面文件資訊了,並且可以直接呼叫介面,還是很方便的。

附錄

整個結構以及大部分內容都是參考部落格,下面會給出連結,還是很推薦的,但是程式碼部分是根據小編的實際編寫來解釋的。以及把日常會用到的情況都做了說明並給出例子。

參考:

  1. https://blog.csdn.net/sanyaoxu_2/article/details/80555328
分享到: