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

Swagger 配置及使用指南

news 2025/7/27 14:43:08

Spring Boot 项目集成 Swagger 配置及使用指南

一、Swagger 简介

Swagger 是一个用于设计、构建、文档化和使用 RESTful API 的框架。通过集成 Swagger，开发者可以：

自动生成实时 API 文档
直接在浏览器中测试 API 接口
减少手动编写文档的工作量
支持团队协作开发

二、环境配置（Spring Boot 2.7.x 示例）

1. 添加 Maven 依赖

<!-- pom.xml -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>3.0.0</version>
</dependency>
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>3.0.0</version>
</dependency>

2. 创建配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 指定扫描包.paths(PathSelectors.any()).build().apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("API 文档").description("Spring Boot 集成 Swagger 示例").version("1.0.0").contact(new Contact("开发者", "https://example.com", "contact@example.com")).build();}
}

3. 解决常见启动问题

# application.yml
spring:mvc:pathmatch:matching-strategy: ANT_PATH_MATCHER # 解决 Spring Boot 2.6+ 版本问题

三、Swagger 注解使用

1. Controller 层注解

@RestController
@Api(tags = "用户管理接口")
@RequestMapping("/api/users")
public class UserController {@ApiOperation(value = "获取用户详情", notes = "根据ID查询用户信息")@GetMapping("/{id}")public ResponseEntity<User> getUser(@ApiParam(value = "用户ID", required = true, example = "1") @PathVariable Long id) {// 业务逻辑}
}

2. Model 层注解

@ApiModel(description = "用户实体")
public class User {@ApiModelProperty(value = "用户ID", example = "1001")private Long id;@ApiModelProperty(value = "用户名", required = true, example = "john_doe")private String username;// getters/setters
}

四、访问与测试

1. 访问文档页面

启动项目后访问：

http://localhost:8080/swagger-ui/index.html

2. 接口测试示例

在 Swagger UI 中找到目标接口
点击 “Try it out”
输入请求参数
点击 “Execute” 发送请求
查看响应结果和状态码

五、高级配置（可选）

1. 安全配置

// 允许访问 Swagger 资源
@Configuration
public class WebConfig implements WebMvcConfigurer {@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/swagger-ui/**").addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");}
}

2. 分组配置

// 创建多个 API 分组
@Bean
public Docket adminApi() {return new Docket(DocumentationType.SWAGGER_2).groupName("管理端接口").select().apis(RequestHandlerSelectors.basePackage("com.example.admin")).build();
}