写点什么

技术分享 | Spring Boot 集成 Swagger

  • 2022 年 9 月 13 日
    北京
  • 本文字数:3804 字

    阅读完需:约 12 分钟

Swagger UI 允许任何人(无论您是开发团队还是最终用户)都可以可视化 API 资源并与之交互,而无需任何实现逻辑。它是根据您的 OpenAPI(以前称为 Swagger)规范自动生成的,具有可视化文档,可简化后端实现和客户端使用。


为什么使用 Swagger 跨语言性,支持 40 多种语言,Swagger 已经慢慢演变成了 OpenAPI 规范;Swagger UI 呈现出来的是一份可交互式的 API 文档,我们可以直接在文档页面尝试 API 的调用,省去了准备复杂的调用参数的过程;对于某些没有前端界面 UI 的功能,可以用它来测试接口;联调方便,如果出问题,直接测试接口,实时检查参数和返回值,就可以快速定位问题。Swagger 快速开始这里选择 2.9.2 版本。


添加配置类


添加一个 Swagger 配置类,在工程下新建 config 包并添加一个 SwaggerConfig 配置类。


SwaggerConfig.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@EnableSwagger2public 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接口文档界面。

测试
展开 hogwarts-test-user-controller 的任意接口,输入参数并点击执行,就可以看到接口测试结果了。
![](https://ceshiren.com/uploads/default/original/3X/3/6/36b43ef05715d1a12be4a8b6407526188d2a9355.png)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 常用注解后的效果![](https://ceshiren.com/uploads/default/original/3X/f/5/f5db74e48ef10841dd6c9a0ec70295f6960f320d.png)
![](https://ceshiren.com/uploads/default/original/3X/e/a/ea5cf30e5fc19aca14af8f102369743f3fc9ae3f.png)添加 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就先讲到这里,大家可以照着代码,多练习一下哦~
复制代码

点击下方链接免费领取:性能测试+接口测试+自动化测试+测试开发+测试用例+简历模板+测试文档

http://qrcode.testing-studio.com/f?from=infoQ&url=https://ceshiren.com/t/topic/22265

用户头像

社区:ceshiren.com 微信:ceshiren2021 2019.10.23 加入

微信公众号:霍格沃兹测试开发 提供性能测试、自动化测试、测试开发等资料,实时更新一线互联网大厂测试岗位内推需求,共享测试行业动态及资讯,更可零距离接触众多业内大佬。

评论

发布
暂无评论
技术分享 | Spring Boot 集成 Swagger_霍格沃兹测试开发学社_InfoQ写作社区