技术分享 | Spring Boot 集成 Swagger

简介: Swagger UI 允许任何人(无论您是开发团队还是最终用户)都可以可视化 API 资源并与之交互,而无需任何实现逻辑。它是根据您的 OpenAPI(以前称为 Swagger)规范自动生成的,具有可视化文档,可简化后端实现和客户端使用。## 为什么使用Swagger- 跨语言性,支持 40 多种语言,Swagger 已经慢慢演变成了 OpenAPI 规范;- Swagger UI 呈现
更多技术文章分享和免费资料领取
https://qrcode.testing-studio.com/f?from=Aliyun&url=https://ceshiren.com/t/topic/16586
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 配置类。作为Springfox框架的主要接口的构建器,提供合理的默认值和方便的配置方法。
    @Bean
    public Docket docket() {

        ParameterBuilder builder = new ParameterBuilder();
        builder.parameterType("header").name("token")
                .description("token值在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:使用该注解忽略这个 API
ApiError :发生错误返回的信息
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就先讲到这里,大家可以照着代码,多练习一下哦~

[原文链接](https://mp.weixin.qq.com/s?__biz=MzU3NDM4ODEzMg==&mid=2247500463&idx=1&sn=24ea9238dc2eb1ce1745530cbe8464be&chksm=fd31a064ca462972926ce900ae0b2e40e1df4629e97cee80a05aee758b49fc8be26b72b97729#rd) 

### ⬇️ 点击“下方链接”,提升测试核心竞争力!
> 更多技术文章分享和免费资料领取
相关文章
|
21天前
|
数据可视化 Java BI
将 Spring 微服务与 BI 工具集成:最佳实践
本文探讨了 Spring 微服务与商业智能(BI)工具集成的潜力与实践。随着微服务架构和数据分析需求的增长,Spring Boot 和 Spring Cloud 提供了构建可扩展、弹性服务的框架,而 BI 工具则增强了数据可视化与实时分析能力。文章介绍了 Spring 微服务的核心概念、BI 工具在企业中的作用,并深入分析了两者集成带来的优势,如实时数据处理、个性化报告、数据聚合与安全保障。同时,文中还总结了集成过程中的最佳实践,包括事件驱动架构、集中配置管理、数据安全控制、模块化设计与持续优化策略,旨在帮助企业构建高效、智能的数据驱动系统。
将 Spring 微服务与 BI 工具集成:最佳实践
|
3月前
|
XML 人工智能 Java
Spring Boot集成Aviator实现参数校验
Aviator是一个高性能、轻量级的Java表达式求值引擎,适用于动态表达式计算。其特点包括支持多种运算符、函数调用、正则匹配、自动类型转换及嵌套变量访问,性能优异且依赖小。适用于规则引擎、公式计算和动态脚本控制等场景。本文介绍了如何结合Aviator与AOP实现参数校验,并附有代码示例和仓库链接。
171 0
|
3月前
|
安全 Java 数据库
第16课:Spring Boot中集成 Shiro
第16课:Spring Boot中集成 Shiro
560 0
|
3月前
|
消息中间件 存储 Java
第15课: Spring Boot中集成ActiveMQ
第15课: Spring Boot中集成ActiveMQ
324 0
|
4月前
|
人工智能 Java 测试技术
Spring Boot 集成 JUnit 单元测试
本文介绍了在Spring Boot中使用JUnit 5进行单元测试的常用方法与技巧,包括添加依赖、编写测试类、使用@SpringBootTest参数、自动装配测试模块(如JSON、MVC、WebFlux、JDBC等),以及@MockBean和@SpyBean的应用。内容实用,适合Java开发者参考学习。
454 0
|
23天前
|
监控 Cloud Native Java
Spring Integration 企业集成模式技术详解与实践指南
本文档全面介绍 Spring Integration 框架的核心概念、架构设计和实际应用。作为 Spring 生态系统中的企业集成解决方案,Spring Integration 基于著名的 Enterprise Integration Patterns(EIP)提供了轻量级的消息驱动架构。本文将深入探讨其消息通道、端点、过滤器、转换器等核心组件,以及如何构建可靠的企业集成解决方案。
85 0
|
3月前
|
Java 关系型数据库 数据库连接
Spring Boot项目集成MyBatis Plus操作PostgreSQL全解析
集成 Spring Boot、PostgreSQL 和 MyBatis Plus 的步骤与 MyBatis 类似,只不过在 MyBatis Plus 中提供了更多的便利功能,如自动生成 SQL、分页查询、Wrapper 查询等。
277 3
|
3月前
|
缓存 JSON 前端开发
第07课:Spring Boot集成Thymeleaf模板引擎
第07课:Spring Boot集成Thymeleaf模板引擎
399 0
第07课:Spring Boot集成Thymeleaf模板引擎
|
4月前
|
监控 安全 Java
Java 开发中基于 Spring Boot 3.2 框架集成 MQTT 5.0 协议实现消息推送与订阅功能的技术方案解析
本文介绍基于Spring Boot 3.2集成MQTT 5.0的消息推送与订阅技术方案,涵盖核心技术栈选型(Spring Boot、Eclipse Paho、HiveMQ)、项目搭建与配置、消息发布与订阅服务实现,以及在智能家居控制系统中的应用实例。同时,详细探讨了安全增强(TLS/SSL)、性能优化(异步处理与背压控制)、测试监控及生产环境部署方案,为构建高可用、高性能的消息通信系统提供全面指导。附资源下载链接:[https://pan.quark.cn/s/14fcf913bae6](https://pan.quark.cn/s/14fcf913bae6)。
576 0