技術標籤：vuevue

Swagger簡介

簡介

Swagger是一款目前世界最流行的API管理工具。目前Swagger已經形成一個生態圈，能夠管理API的整個生命周 期，從設計、文件到測試與部署。

特性：

程式碼侵入式註解
遵循YAML文件格式
非常適合三端（PC、iOS及Android）的API管理，尤其適合前後端完全分離的架構模式。
減少沒有必要的文件，符合敏捷開發理念
功能強大

作用

介面的文件線上自動生成
功能測試

優點

大大減少前後端的溝通
方便查詢和測試介面
提高團隊的開發效率
方便新人瞭解專案

配置swagger

引入依賴

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

配置類

package com.lxs.upload.config; 
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; 

@Configuration 
@EnableSwagger2 
public class SwaggerConfig { 
	@Bean 
	public Docket createRestApi() { 
		return new Docket(DocumentationType.SWAGGER_2) 
			.apiInfo(apiInfo()) 
			.select() 
			.apis(RequestHandlerSelectors
			.basePackage("com.lxs.upload")) //swagger搜尋的包 
			.paths(PathSelectors.any()) //swagger路徑匹配 
			.build(); 
	}
	private ApiInfo apiInfo() { 
		return new ApiInfoBuilder() 
			.title("檔案上傳文件") 
			.description("使用FastDfs檔案上傳") 
			.version("version 1.0") 
			.build(); 
	} 
}

常用註解

swagger通過在controller中，宣告註解，API文件進行說明
1、@Api()：用在請求的類上，表示對類的說明，也代表了這個類是swagger2的資源
引數：

• tags：說明該類的作用，引數是個陣列，可以填多個。
  value=“該引數沒什麼意義，在UI介面上不顯示，所以不用配置”
  description = “使用者基本資訊操作”

2、@ApiOperation()：用於方法，表示一個http請求訪問該方法的操作
引數：

• value=“方法的用途和作用”
  notes=“方法的注意事項和備註”
  tags：說明該方法的作用，引數是個陣列，可以填多個。
  格式：tags={“作用1”,“作用2”} （在這裡建議不使用這個引數，會使介面看上去有點亂，前兩個常用）

3、@ApiModel()：用於響應實體類上，用於說明實體作用
引數：

• description=“描述實體的作用”

4、@ApiModelProperty：用在屬性上，描述實體類的屬性
引數：

• value=“使用者名稱” 描述引數的意義
  name=“name” 引數的變數名
  required=true 引數是否必選

5、@ApiImplicitParams：用在請求的方法上，包含多@ApiImplicitParam
6、@ApiImplicitParam：用於方法，表示單獨的請求引數
引數：

• name=“引數ming”
  value=“引數說明”
  dataType=“資料型別”
  paramType=“query” 表示引數放在哪裡
  · header 請求引數的獲取：@RequestHeader
  · query 請求引數的獲取：@RequestParam
  · path（用於restful介面） 請求引數的獲取：@PathVariable
  · body（不常用）
  · form（不常用）
  defaultValue=“引數的預設值”
  required=“true” 表示引數是否必須傳

7、@ApiParam()：用於方法，引數，欄位說明 表示對引數的要求和說明
引數：

• name=“引數名稱”
  value=“引數的簡要說明”
  defaultValue=“引數預設值”
  required=“true” 表示屬性是否必填，預設為false

8、@ApiResponses：用於請求的方法上，根據響應碼錶示不同響應
一個@ApiResponses包含多個@ApiResponse
9、@ApiResponse：用在請求的方法上，表示不同的響應
引數：

• code=“404” 表示響應碼(int型)，可自定義
  message=“狀態碼對應的響應資訊”

10、@ApiIgnore()：用於類或者方法上，不被顯示在頁面上

使用

實體類

@ApiModel("使用者物件模型") 
public class User { 
	private Long id; 
	private String username; 
	private String password; 
	private String email; 

controller

package com.lxs.upload.controller; 
import com.lxs.upload.domain.User; 
import io.swagger.annotations.*; 
import org.springframework.http.HttpStatus; 
import org.springframework.http.ResponseEntity; 
import org.springframework.web.bind.annotation.*; 
import springfox.documentation.annotations.ApiIgnore; 
import javax.xml.ws.Response;

 /**
 * /user post 新增 
 */ 
@RestController 
@RequestMapping("/user") 
@Api(tags = {"使用者管理API"}) 
public class UserController { 
		@PostMapping 
		@ApiOperation(value = "新增使用者", notes = "新增後返回當前使用者") 
		@ApiResponses({ 
			@ApiResponse(code = 200, message = "返回成功", response = User.class), 			
			@ApiResponse(code = 400, message = "引數沒有填好(id==1)", response = User.class), 
			@ApiResponse(code = 401, message = "許可權不足(id==1)", response = User.class), 
		})
		public ResponseEntity<User> add(User user) { 
			if (user.getId() == 1) { 
				return new ResponseEntity<>(user, HttpStatus.BAD_REQUEST); //400 
			} else if (user.getId() == 2) { 
				return new ResponseEntity<>(user, HttpStatus.UNAUTHORIZED); //401 
			} else { 
				return ResponseEntity.ok(user); 
			} 
		}
}

測試

Swagger預設提供了API展示UI springfox-swagger-ui ，啟動工程後可以訪問如下路徑檢視api資訊：
http://localhost:9093/swagger-ui.html

除了預設的UI，國內還有一個優秀的Swagger-Bootstrap-UI 基於Swagger 的前端UI ，採用jQuery+bootstrap實現。因Swagger 的預設UI 是上下結構的，用起來不太習慣，所以用Swagger-Bootstrap-UI 替換Swagger 預設的UI實現 左右選單風格的Swagger-UI ，讓其看起來更清晰明瞭。
使用方法：

1. 新增依賴

<dependency> 
	<groupId>com.github.xiaoymin</groupId> 
	<artifactId>swagger-bootstrap-ui</artifactId> 
	<version>1.9.3</version> 
</dependency>

重啟啟動器
2. 訪問路徑
http://localhost:9093/doc.html