Spring Boot系列十九 Spring boot整合 swagger

hryou0922發表於2019-03-03

Swagger簡述

Swagger 是一款RESTFUL介面的文件線上自動生成+功能測試功能軟體
Swagger 是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。總體目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法，引數和模型緊密整合到伺服器端的程式碼，允許API來始終保持同步

Spring Boot整合Swagger

本文涉及的工程： swagger

pom.xml
swagger需要引入如下的jar

<!--  引入swagger包 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>
複製程式碼

@EnableSwagger2
使用@EnableSwagger2註解在Control類上就可以swagger的功能

@RestController
@EnableSwagger2 // 啟動swagger註解
// api-value：定義名稱，如果沒有定義，則預設顯示類名
@Api(value = "Swagger Test Control", description = "演示Swagger用法的Control類", tags = "Swagger Test Control Tag")
public class SwaggerTestCtl {
..
}
複製程式碼

執行啟動類
執行啟動類，訪問如下連線
http://127.0.0.1:8080/swagger-ui.html#/
就可以進入swagger頁面，進行介面測試，介面如下:

ApiInfo類

我們建立ApiInfo例項，我們為swagger配置更多的介面說明

@Bean
public Docket api() {
	return new Docket(DocumentationType.SWAGGER_2)
		.apiInfo(getApiInfo())
		// .pathMapping("/")// base，最終呼叫介面後會和paths拼接在一起
		.select()
		// .paths(Predicates.or(PathSelectors.regex("/api/.*")))//過濾的介面
		.apis(RequestHandlerSelectors.basePackage("com.hry.swagger.ctl")) //過濾的介面
		.paths(PathSelectors.any())
		.build();
}

private ApiInfo getApiInfo() {
	// 定義聯絡人資訊
	Contact contact = new Contact("hryou0922","https://github.com/hryou0922", "hryou0922@126.com");
	return new ApiInfoBuilder()
		.title("演示 Swagger 的用法") // 標題
		.description("演示Swagger中各種註解的用法") // 描述資訊
		.version("1.1.2") // //版本
		.license("Apache 2.0")
		.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
		.contact(contact)
		.build();
}
複製程式碼

重啟服務，介面如下：

swagger的註解

swagger的註解概述

我們可以使用swagger定義更詳細介面說明

@Api：用在類上，標誌此類是Swagger資源
	value：介面說明
	tags：介面說明，可以在頁面中顯示。可以配置多個，當配置多個的時候，在頁面中會顯示多個介面的資訊

@ApiOperation：用在方法上，描述方法的作用

@ApiImplicitParams：包裝器：包含多個ApiImplicitParam物件列表

@ApiImplicitParam：定義在@ApiImplicitParams註解中，定義單個引數詳細資訊
		○ paramType：引數放在哪個地方
			§ header-->請求引數的獲取：@RequestHeader
			§ query-->請求引數的獲取：@RequestParam
			§ path（用於restful介面）-->請求引數的獲取：@PathVariable
			§ body（以流的形式提交 僅支援POST）
			§ form（以form表單的形式提交 僅支援POST）
		○ name：引數名
		○ dataType：引數的資料型別 只作為標誌說明，並沒有實際驗證
			§ Long
			§ String
		○ required：引數是否必須傳
			§ true
			§ false
		○ value：引數的意義
		○ defaultValue：引數的預設值

@ApiModel：描述一個Swagger Model的額外資訊
	@ApiModel用在類上，表示對類進行說明，用於實體類中的引數接收說明
	
@ApiModelProperty：在model類的屬性新增屬性說明

@ApiParam：用於Controller中方法的引數說明

@ApiResponses：包裝器：包含多個ApiResponse物件列表
	
@ApiResponse：定義在@ApiResponses註解中，一般用於描述一個錯誤的響應資訊
		○ code：錯誤碼，例如400
		○ message：資訊，例如"請求引數沒填好"
		○ response：丟擲異常的類
		
@Authorization	Declares an authorization scheme to be used on a resource or an operation.

@AuthorizationScope	Describes an OAuth2 authorization scope.
複製程式碼

##演示使用註解demo
本節我們演示上節的註解如何使用
###@Api
用在類上，標誌此類是Swagger資源，對介面更加詳細說明

@RestController
@EnableSwagger2 // 啟動swagger註解
@Api(value = "Swagger Test Control", description = "演示Swagger用法的Control類", tags = "Swagger Test Control Tag")
public class SwaggerTestCtl {

}
複製程式碼

結果如下:

###@ApiOperation
用在方法上，描述方法的作用

// 方法的說明
@ApiOperation(value = "根據id獲取記錄", response = Student.class)
// 定義請求引數
@ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "String", name = "id", value = "主鍵", required = true) })
public Student queryById(String id){
    System.out.println("queryById id = " + id);
    return new Student();
}
複製程式碼

結果如下:

@ApiImplicitParams 和 @ApiImplicitParam

// 定義請求引數
@ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "String", name = "id", value = "主鍵", required = true) })
public Student queryById(String id){
   System.out.println("queryById id = " + id);
   return new Student();
}

複製程式碼

結果如下:

###@ApiModel 和@ApiModelProperty

定義model類

@ApiModel( description = "學生")
public class Student {
    @ApiModelProperty(value = "主鍵id")
    private String id;
    @ApiModelProperty(value = "名稱", required = true)
    private String name;
    @ApiModelProperty(value = "年齡", required = true)
    private int age;
…
}
複製程式碼

在方法使用

@RequestMapping(value = "/update", method = {RequestMethod.POST})
// 方法說明
@ApiOperation(value = "新增學生記錄", notes="傳遞複雜物件DTO",produces = "application/json")
public int update(@RequestBody Student student){
    System.out.println("update student = " + student);
    return 1;
}
複製程式碼

結果如下:

@ApiResponses和@ApiResponse

@RequestMapping(value = "/del", method = {RequestMethod.POST, RequestMethod.GET})
// 方法說明
@ApiOperation(value = "刪除學生記錄學生記錄")
// 定義返回值意義
@ApiResponses({
        @ApiResponse(code = 400, message = "伺服器內部異常"),
        @ApiResponse(code = 500, message = "許可權不足") })
public int del(int id){
    System.out.println("del id = " + id);
    return 1;
}  
複製程式碼

結果如下: