技術分享 | Spring Boot 整合 Swagger
阿新 • • 發佈：2022-05-23
Swagger UI 允許任何人（無論您是開發團隊還是終端使用者）都可以視覺化 API 資源並與之互動，而無需任何實現邏輯。它是根據您的 OpenAPI（以前稱為 Swagger）規範自動生成的，具有視覺化文件，可簡化後端實現和客戶端使用。
為什麼使用Swagger
- 跨語言性，支援 40 多種語言，Swagger 已經慢慢演變成了 OpenAPI 規範；
- Swagger UI 呈現出來的是一份可互動式的 API 文件，我們可以直接在文件頁面嘗試 API 的呼叫，省去了準備複雜的呼叫引數的過程；
- 對於某些沒有前端介面 UI 的功能，可以用它來測試介面；
- 聯調方便，如果出問題，直接測試介面，實時檢查引數和返回值,就可以快速定位問題。
Swagger快速開始
這裡選擇 2.9.2 版本。
<!-- 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>
新增配置類
新增一個 Swagger 配置類，在工程下新建 config 包並新增一個 SwaggerConfig 配置類。
SwaggerConfig.java
```java
import com.google.common.collect.Lists;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
//作為Springfox框架的主要介面的構建器,提供合理的預設值和方便的配置方法。
@Bean
public Docket docket() {
ParameterBuilder builder = new ParameterBuilder();
builder.parameterType("header").name("token")
.description("token值")
.required(true)
.modelRef(new ModelRef("string")); // 在swagger裡顯示header
return new Docket(DocumentationType.SWAGGER_2)
.groupName("aitest_interface")
.apiInfo(apiInfo())
.globalOperationParameters(Lists.newArrayList(builder.build()))
.select().paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("aitest-mini系統")
.description("aitest-mini介面文件")
.contact(new Contact("tlibn", "", "[email protected]"))
.version("1.0")
.build();
}
}
新增控制器
新增一個控制器，在工程下新建 controller包並新增一個Controller控制器，如果已經存在Controller控制器，則直接啟動服務也可以，如上章我們編寫了HogwartsTestUserController類，此時直接啟動服務即可。
開啟 swagger 介面文件介面
啟動 Spring Boot 服務，開啟瀏覽器，訪問：http://127.0.0.1:8081/swagger-ui.html，進入swagger介面文件介面。 4
測試
展開 hogwarts-test-user-controller 的任意介面，輸入引數並點選執行，就可以看到介面測試結果了。
Swagger 常用註解
swagger 通過註解表明該介面會生成文件，包括介面名、請求方法、引數、返回資訊的等等。
Api：修飾整個類，描述 Controller 的作用
Api(tags = “霍格沃茲測試學院-使用者管理模組”, hidden = true)
ApiOperation：描述一個類的一個方法，或者說一個介面
ApiOperation(“查詢使用者列表”)
ApiParam：單個引數描述
ApiModel：用物件來接收引數
ApiModel(value = “使用者登入類”, description = “請求類”)
ApiProperty：用物件接收引數時，描述物件的一個欄位
ApiModelProperty(value=“使用者id”, example=“1”,required=true)
ApiResponse：HTTP 響應其中 1 個描述
ApiResponses：HTTP 響應整體描述
ApiIgnore：使用該註解忽略這個 API
ApiError ：發生錯誤返回的資訊
ApiImplicitParam：一個請求引數
ApiImplicitParams：多個請求引數
更多參見 https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#quick-annotation-overview
新增 Swagger 常用註解後的效果
新增 Swagger 常用註解後的示例程式碼
HogwartsTestUserController.java
@Api(tags = “霍格沃茲測試學院-使用者管理模組”, hidden = true)
@RestController
@RequestMapping("/api/user")
public class HogwartsTestUserController {
/**
* 查詢使用者列表，返回一個JSON陣列
* */
@ApiOperation("查詢使用者列表")
@GetMapping("/users")
@ResponseStatus(HttpStatus.OK)
public Object getUsers(){
List<UserDto> list = getData();
return list;
}
/**
* 查詢使用者資訊，返回一個新建的JSON物件
* */
@ApiOperation("查詢使用者資訊")
@GetMapping("/users/{id}")
@ResponseStatus(HttpStatus.OK)
public Object getUser(@PathVariable("id") Long id){
if(Objects.isNull(id)){
return null;
}
List<UserDto> list= getData();
UserDto userDto = getUserDto(id, list);
return userDto;
}
/**
* 新增使用者
* */
@ApiOperation("新增使用者")
@PostMapping("/users")
@ResponseStatus(HttpStatus.CREATED)
public Object addUser(@RequestBody UserDto user){
List<UserDto> list= getData();
list.add(user);//模擬向列表中增加資料
return user;
}
/**
* 編輯使用者
* */
@ApiOperation("編輯使用者")
@PutMapping("/users/{id}")
@ResponseStatus(HttpStatus.CREATED)
public Object editUser(@PathVariable("id") Long id,@RequestBody UserDto user){
List<UserDto> list = getData();
for (UserDto userDto:list) {
if(id.equals(userDto.getId())){
userDto = user;
break;
}
}
return user;
}
/**
* 刪除使用者
* */
@ApiOperation("刪除使用者")
@DeleteMapping("/users/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public Object deleteUser(@PathVariable("id") Long id){
List<UserDto> list = getData();
UserDto userDto = getUserDto(id, list);
return userDto;
}
/**
* 模擬資料
* */
private List<UserDto> getData(){
List<UserDto> list=new ArrayList<>();
UserDto userDto = new UserDto();
userDto.setId(1L);
userDto.setName("admin");
userDto.setPwd("admin");
list.add(userDto);
userDto = new UserDto();
userDto.setId(2L);
userDto.setName("HogwartsTest1");
userDto.setPwd("HogwartsTest1");
list.add(userDto);
userDto = new UserDto();
userDto.setId(3L);
userDto.setName("HogwartsTest2");
userDto.setPwd("HogwartsTest2");
list.add(userDto);
userDto = new UserDto();
userDto.setId(4L);
userDto.setName("HogwartsTest3");
userDto.setPwd("HogwartsTest3");
list.add(userDto);
return list;
}
/**
* 模擬根據id查詢列表中的資料
* @param id
* @param list
* @return
*/
private UserDto getUserDto( Long id, List<UserDto> list) {
UserDto UserDto = null;
for (UserDto user : list) {
if (id.equals(user.getId())) {
UserDto = user;
break;
}
}
return UserDto;
}
}
UserDto.java
@ApiModel(value = “使用者登入類”, description = “請求類”)
public class UserDto {
@ApiModelProperty(value="使用者id", example="1",required=true)
private Long id;
@ApiModelProperty(value="使用者名稱稱", example="hogwarts1",required=true)
private String name;
@ApiModelProperty(value="使用者密碼", example="hogwarts2",required=true)
private String pwd;
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getPwd() {
return pwd;
}
public void setPwd(String pwd) {
this.pwd = pwd;
}
}
Spring Boot 整合 Swagger就先講到這裡，大家可以照著程式碼，多練習一下哦~