当前位置：首页 > news >正文

SpringBoot整合Swagger2快速指南

news 2025/7/13 6:28:35

Swagger简介

Swagger是一款强大的API文档生成工具，它能够自动为RESTful API生成可视化文档，支持在线测试接口，极大提高了前后端协作效率。本文将详细介绍如何在SpringBoot项目中整合Swagger2。

环境准备

版本要求

重要提示：SpringBoot版本不能过高，推荐使用2.5.6版本：

<parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.5.6</version>
</parent>

添加依赖

<!-- Swagger UI可视化界面 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>
<!-- Swagger2核心依赖 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency>

Swagger配置类

基础配置类

创建SwaggerConfig.java配置类：

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any()).build().enable(true);}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("API文档").description("接口文档详情信息").version("1.0").contact(new Contact("开发者", "", "developer@example.com")).licenseUrl("").build();}@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}
}

配置说明

@EnableSwagger2：启用Swagger2功能
Docket：Swagger的核心配置类
apiInfo()：设置文档的基本信息
addResourceHandlers()：配置静态资源映射

Swagger注解详解

控制器层注解

类级别注解：

@Controller
@RequestMapping("/user")
@Api(tags = {"用户信息接口"})
public class UserController {// ...
}

方法级别注解：

@Controller
@RequestMapping("/user")
@Api(tags = {"用户信息接口"})
public class UserController {// ...
}

参数注解

简单参数：

@ApiImplicitParams({@ApiImplicitParam(value = "用户名", name = "userName", dataType = "string"),@ApiImplicitParam(value = "年龄", name = "age", dataType = "integer")
})
public List<User> findAll(String userName, int age) {// ...
}

实体类参数：

@ApiModel("用户类实体信息")
public class User {@ApiModelProperty(value = "用户id", example = "1")private Integer id;@ApiModelProperty(value = "用户名", example = "张三")private String username;// 其他属性...
}