Swagger UI 允許任何人（無論您是開發(fā)團(tuán)隊(duì)還是最終用戶）都可以可視化 API 資源并與之交互捌斧，而無需任何實(shí)現(xiàn)邏輯。它是根據(jù)您的 OpenAPI（以前稱為 Swagger）規(guī)范自動(dòng)生成的籍茧，具有可視化文檔蚓曼，可簡化后端實(shí)現(xiàn)和客戶端使用。
為什么使用Swagger
- 跨語言性姥芥，支持 40 多種語言嗽桩，Swagger 已經(jīng)慢慢演變成了 OpenAPI 規(guī)范钟鸵；
- Swagger UI 呈現(xiàn)出來的是一份可交互式的 API 文檔，我們可以直接在文檔頁面嘗試 API 的調(diào)用涤躲，省去了準(zhǔn)備復(fù)雜的調(diào)用參數(shù)的過程棺耍；
- 對(duì)于某些沒有前端界面 UI 的功能，可以用它來測(cè)試接口种樱；
- 聯(lián)調(diào)方便蒙袍，如果出問題俊卤，直接測(cè)試接口，實(shí)時(shí)檢查參數(shù)和返回值,就可以快速定位問題害幅。
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>
添加配置類
添加一個(gè) Swagger 配置類，在工程下新建 config 包并添加一個(gè) 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框架的主要接口的構(gòu)建器,提供合理的默認(rèn)值和方便的配置方法狠怨。
@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系統(tǒng)")
.description("aitest-mini接口文檔")
.contact(new Contact("tlibn", "", "103@qq.com"))
.version("1.0")
.build();
}
}
添加控制器
添加一個(gè)控制器，在工程下新建 controller包并添加一個(gè)Controller控制器邑遏，如果已經(jīng)存在Controller控制器佣赖，則直接啟動(dòng)服務(wù)也可以，如上章我們編寫了HogwartsTestUserController類记盒，此時(shí)直接啟動(dòng)服務(wù)即可憎蛤。
打開 swagger 接口文檔界面
啟動(dòng) Spring Boot 服務(wù)，打開瀏覽器纪吮，訪問：http://127.0.0.1:8081/swagger-ui.html俩檬，進(jìn)入swagger接口文檔界面。
測(cè)試
展開 hogwarts-test-user-controller 的任意接口碾盟，輸入?yún)?shù)并點(diǎn)擊執(zhí)行棚辽，就可以看到接口測(cè)試結(jié)果了。
[圖片上傳失敗...(image-769100-1654759268643)]
Swagger 常用注解
swagger 通過注解表明該接口會(huì)生成文檔冰肴，包括接口名屈藐、請(qǐng)求方法、參數(shù)嚼沿、返回信息的等等。
Api：修飾整個(gè)類瓷患，描述 Controller 的作用
Api(tags = "霍格沃茲測(cè)試學(xué)院-用戶管理模塊", hidden = true)
ApiOperation：描述一個(gè)類的一個(gè)方法骡尽，或者說一個(gè)接口
ApiOperation("查詢用戶列表")
ApiParam：單個(gè)參數(shù)描述
ApiModel：用對(duì)象來接收參數(shù)
ApiModel(value = "用戶登錄類", description = "請(qǐng)求類")
ApiProperty：用對(duì)象接收參數(shù)時(shí)，描述對(duì)象的一個(gè)字段
ApiModelProperty(value="用戶id", example="1",required=true)
ApiResponse：HTTP 響應(yīng)其中 1 個(gè)描述
ApiResponses：HTTP 響應(yīng)整體描述
ApiIgnore：使用該注解忽略這個(gè) API
ApiError ：發(fā)生錯(cuò)誤返回的信息
ApiImplicitParam：一個(gè)請(qǐng)求參數(shù)
ApiImplicitParams：多個(gè)請(qǐng)求參數(shù)
更多參見 https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#quick-annotation-overview
添加 Swagger 常用注解后的效果
添加 Swagger 常用注解后的示例代碼
HogwartsTestUserController.java
@Api(tags = "霍格沃茲測(cè)試學(xué)院-用戶管理模塊", hidden = true)
@RestController
@RequestMapping("/api/user")
public class HogwartsTestUserController {
/**
* 查詢用戶列表擅编，返回一個(gè)JSON數(shù)組
* */
@ApiOperation("查詢用戶列表")
@GetMapping("/users")
@ResponseStatus(HttpStatus.OK)
public Object getUsers(){
List<UserDto> list = getData();
return list;
}
/**
* 查詢用戶信息攀细，返回一個(gè)新建的JSON對(duì)象
* */
@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);//模擬向列表中增加數(shù)據(jù)
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;
}
/**
* 模擬數(shù)據(jù)
* */
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;
}
/**
* 模擬根據(jù)id查詢列表中的數(shù)據(jù)
* @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 = "請(qǐng)求類")
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就先講到這里，大家可以照著代碼爱态，多練習(xí)一下哦~
[原文鏈接](https://mp.weixin.qq.com/s?__biz=MzU3NDM4ODEzMg==&mid=2247500463&idx=1&sn=24ea9238dc2eb1ce1745530cbe8464be&chksm=fd31a064ca462972926ce900ae0b2e40e1df4629e97cee80a05aee758b49fc8be26b72b97729#rd)
[更多技術(shù)文章](https://qrcode.ceba.ceshiren.com/link?name=article&project_id=qrcode&from=jianshu×tamp=1652589012&author=BB)
喜歡軟件測(cè)試的小伙伴們谭贪，如果我的博客對(duì)你有幫助、如果你喜歡我的博客內(nèi)容锦担，請(qǐng) “點(diǎn)贊” “評(píng)論” “收藏” 一鍵三連哦俭识！
