技术分享 | Spring Boot 集成 Swagger 技术分享 | Spring Boot 集成 Swagger

简介: 技术分享 | Spring Boot 集成 Swagger

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接口文档界面。 4

测试
展开 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就先讲到这里,大家可以照着代码,多练习一下哦~
相关文章
|
27天前
|
XML Java 应用服务中间件
Spring Boot 两种部署到服务器的方式
本文介绍了Spring Boot项目的两种部署方式:jar包和war包。Jar包方式使用内置Tomcat,只需配置JDK 1.8及以上环境,通过`nohup java -jar`命令后台运行,并开放服务器端口即可访问。War包则需将项目打包后放入外部Tomcat的webapps目录,修改启动类继承`SpringBootServletInitializer`并调整pom.xml中的打包类型为war,最后启动Tomcat访问应用。两者各有优劣,jar包更简单便捷,而war包适合传统部署场景。需要注意的是,war包部署时,内置Tomcat的端口配置不会生效。
202 17
Spring Boot 两种部署到服务器的方式
|
22天前
|
监控 Java 应用服务中间件
SpringBoot是如何简化Spring开发的,以及SpringBoot的特性以及源码分析
Spring Boot 通过简化配置、自动配置和嵌入式服务器等特性,大大简化了 Spring 应用的开发过程。它通过提供一系列 `starter` 依赖和开箱即用的默认配置,使开发者能够更专注于业务逻辑而非繁琐的配置。Spring Boot 的自动配置机制和强大的 Actuator 功能进一步提升了开发效率和应用的可维护性。通过对其源码的分析,可以更深入地理解其内部工作机制,从而更好地利用其特性进行开发。
42 6
|
1月前
|
监控 Java Nacos
使用Spring Boot集成Nacos
通过上述步骤,Spring Boot应用可以成功集成Nacos,利用Nacos的服务发现和配置管理功能来提升微服务架构的灵活性和可维护性。通过这种集成,开发者可以更高效地管理和部署微服务。
196 17
|
1月前
|
缓存 安全 Java
Spring Boot 3 集成 Spring Security + JWT
本文详细介绍了如何使用Spring Boot 3和Spring Security集成JWT,实现前后端分离的安全认证概述了从入门到引入数据库,再到使用JWT的完整流程。列举了项目中用到的关键依赖,如MyBatis-Plus、Hutool等。简要提及了系统配置表、部门表、字典表等表结构。使用Hutool-jwt工具类进行JWT校验。配置忽略路径、禁用CSRF、添加JWT校验过滤器等。实现登录接口,返回token等信息。
347 12
|
1月前
|
人工智能 安全 Dubbo
Spring AI 智能体通过 MCP 集成本地文件数据
MCP 作为一款开放协议,直接规范了应用程序如何向 LLM 提供上下文。MCP 就像是面向 AI 应用程序的 USB-C 端口,正如 USB-C 提供了一种将设备连接到各种外围设备和配件的标准化方式一样,MCP 提供了一个将 AI 模型连接到不同数据源和工具的标准化方法。
|
1月前
|
存储 安全 Java
Spring Boot 3 集成Spring AOP实现系统日志记录
本文介绍了如何在Spring Boot 3中集成Spring AOP实现系统日志记录功能。通过定义`SysLog`注解和配置相应的AOP切面,可以在方法执行前后自动记录日志信息,包括操作的开始时间、结束时间、请求参数、返回结果、异常信息等,并将这些信息保存到数据库中。此外,还使用了`ThreadLocal`变量来存储每个线程独立的日志数据,确保线程安全。文中还展示了项目实战中的部分代码片段,以及基于Spring Boot 3 + Vue 3构建的快速开发框架的简介与内置功能列表。此框架结合了当前主流技术栈,提供了用户管理、权限控制、接口文档自动生成等多项实用特性。
81 8
|
2月前
|
缓存 前端开发 Java
【Spring】——SpringBoot项目创建
SpringBoot项目创建,SpringBootApplication启动类,target文件,web服务器,tomcat,访问服务器
|
3月前
|
监控 Java 数据库连接
详解Spring Batch:在Spring Boot中实现高效批处理
详解Spring Batch:在Spring Boot中实现高效批处理
465 12
|
3月前
|
安全 Java 测试技术
详解Spring Profiles:在Spring Boot中实现环境配置管理
详解Spring Profiles:在Spring Boot中实现环境配置管理
155 10
|
2月前
|
XML Java API
Spring Boot集成MinIO
本文介绍了如何在Spring Boot项目中集成MinIO,一个高性能的分布式对象存储服务。主要步骤包括:引入MinIO依赖、配置MinIO属性、创建MinIO配置类和服务类、使用服务类实现文件上传和下载功能,以及运行应用进行测试。通过这些步骤,可以轻松地在项目中使用MinIO的对象存储功能。
147 5