Swagger详细使用介绍

Swagger 是一个用于生成、描述、调用和可视化 RESTful Web 服务的工具。它通过注解和配置自动生成 API 文档，并提供交互式的 API 测试界面。以下是 Swagger 的详细使用介绍，包含配置、注解、案例及最佳实践。

---

一、Swagger 简介

Swagger 的核心功能：

自动生成 API 文档：通过注解描述 API，自动生成文档。交互式测试界面：直接在浏览器中测试 API。支持多种语言：Java、Python、Node.js 等。OpenAPI 规范：遵循 OpenAPI 规范，生成的文档可与其他工具兼容。

---

二、Spring Boot 集成 Swagger 1. 添加依赖

在 pom.xml 中添加 Swagger 依赖：

<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. 配置 Swagger

创建一个配置类启用 Swagger：

import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(new ApiInfoBuilder() .title("API 文档") .description("Spring Boot 集成 Swagger") .version("1.0") .build()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 扫描的包路径 .paths(PathSelectors.any()) .build(); } } 3. 访问 Swagger UI

启动项目后，访问以下 URL：

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

---

三、Swagger 注解详解

Swagger 通过注解描述 API，以下是常用注解：

1. 类级别注解 注解作用示例@Api描述控制器类@Api(tags = "用户管理")@ApiModel描述实体类@ApiModel("用户实体")@ApiOperation描述接口方法@ApiOperation("获取用户信息") 2. 方法级别注解 注解作用示例@ApiOperation描述接口方法@ApiOperation("获取用户信息")@ApiParam描述方法参数@ApiParam("用户ID")@ApiResponse描述响应状态码@ApiResponse(code = 200, message = "成功") 3. 字段级别注解 注解作用示例@ApiModelProperty描述实体类字段@ApiModelProperty("用户ID")

---

四、Swagger 使用案例 1. 控制器示例 import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/user") @Api(tags = "用户管理") public class UserController { @GetMapping("/{id}") @ApiOperation("根据ID获取用户信息") public String getUserById(@PathVariable @ApiParam("用户ID") Long id) { return "用户ID：" + id; } @PostMapping @ApiOperation("创建用户") public String createUser(@RequestBody User user) { return "创建用户：" + user.getName(); } } 2. 实体类示例 import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; @ApiModel("用户实体") public class User { @ApiModelProperty("用户ID") private Long id; @ApiModelProperty("用户姓名") private String name; // Getter 和 Setter }

---

五、Swagger 高级配置 1. 分组配置

如果需要为不同的模块生成不同的文档，可以配置多个 Docket：

@Bean public Docket userApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("用户管理") .select() .apis(RequestHandlerSelectors.basePackage("com.example.user")) .paths(PathSelectors.any()) .build(); } @Bean public Docket orderApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("订单管理") .select() .apis(RequestHandlerSelectors.basePackage("com.example.order")) .paths(PathSelectors.any()) .build(); } 2. 全局参数配置

如果需要为所有接口添加全局参数（如 Token），可以配置全局参数：

@Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .globalRequestParameters(Arrays.asList( new RequestParameterBuilder() .name("token") .description("用户Token") .in(ParameterType.HEADER) .required(true) .build() )) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .paths(PathSelectors.any()) .build(); }

---

六、Swagger 最佳实践 统一响应格式： 使用统一的响应类（如 Result<T>），并在 Swagger 中描述。 分模块管理： 为不同的功能模块配置不同的 Docket。 生产环境禁用： 在生产环境中禁用 Swagger，避免暴露 API 信息。 spring: profiles: active: prod swagger: enabled: false

---

七、总结 Swagger 是一个强大的 API 文档工具，能够自动生成文档并提供交互式测试界面。通过注解和配置，可以灵活地描述 API 和实体类。结合 Spring Boot，可以快速集成 Swagger 并生成高质量的 API 文档。