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", "", "103@qq.com"))
.version("1.0")
.build();
}
}
添加控制器
复制代码
添加一个控制器,在工程下新建 controller 包并添加一个 Controller 控制器,如果已经存在 Controller 控制器,则直接启动服务也可以,如上章我们编写了 HogwartsTestUserController 类,此时直接启动服务即可。
打开 swagger 接口文档界面启动 Spring Boot 服务,打开浏览器,访问:http://127.0.0.1:8081/swagger-ui.html,进入 swagger 接口文档界面。 6
测试
展开 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:使用该注解忽略这个 APIApiError :发生错误返回的信息 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 就先讲到这里,大家可以照着代码,多练习一下哦~
更多学习资料戳下方!!!
https://qrcode.ceba.ceshiren.com/link?name=article&project_id=qrcode&from=infoQ×tamp=1662366626&author=xueqi
评论