什么是 Swagger？

Swagger 是一个开源的 API 文档生成工具，专门用于描述、生产、消费 RESTful Web 服务。它通过标准化的格式（OpenAPI 规范）生成易于理解和交互的 API 文档。Swagger 不仅支持 API 文档生成，还可以提供自动化的 UI 界面，方便开发人员和测试人员查看和使用 API。

Swagger 提供的主要功能：

1. 自动化文档生成：通过注解，Swagger 可以自动从代码中生成 API 文档。
2. API 测试：Swagger UI 提供了一个可交互的界面，允许用户直接在浏览器中测试 API 请求。
3. 代码生成：Swagger 支持根据 API 描述生成客户端代码、服务端代码等。
4. 标准化接口文档：Swagger 文档遵循 OpenAPI 规范（以前叫 Swagger 规范），提供了一个标准的格式，方便与其他工具和服务集成。

Swagger 与 Spring Boot 集成

在 Spring Boot 中，集成 Swagger 主要是通过使用 springfox-swagger2 和 springfox-swagger-ui 来实现自动生成 API 文档和交互式 UI 界面。

1. 添加依赖

在 Spring Boot 项目中，你可以通过在 pom.xml 文件中添加以下依赖来集成 Swagger：

复制
1<dependencies>
2    <!-- Swagger 2 依赖 -->
3    <dependency>
4        <groupId>io.springfox</groupId>
5        <artifactId>springfox-swagger2</artifactId>
6        <version>2.9.2</version>
7    </dependency>
8
9    <!-- Swagger UI 依赖 -->
10    <dependency>
11        <groupId>io.springfox</groupId>
12        <artifactId>springfox-swagger-ui</artifactId>
13        <version>2.9.2</version>
14    </dependency>
15</dependencies>

注意：这里使用的是 springfox-swagger2，它适用于 Spring Boot 2.x 以下版本。如果你使用的是 Spring Boot 2.x 以上版本，建议使用 springdoc-openapi 作为替代。

2. 配置 Swagger

在 Spring Boot 中，配置 Swagger 只需要添加一个配置类，并通过注解告诉 Swagger 如何扫描你的 API。

复制
1import org.springframework.context.annotation.Bean;
2import org.springframework.context.annotation.Configuration;
3import springfox.documentation.builders.ApiInfoBuilder;
4import springfox.documentation.builders.PathSelectors;
5import springfox.documentation.builders.RequestHandlerSelectors;
6import springfox.documentation.spi.DocumentationType;
7import springfox.documentation.spring.web.plugins.Docket;
8import springfox.documentation.swagger2.annotations.EnableSwagger2;
9
10@Configuration
11@EnableSwagger2  // 启用Swagger2
12public class SwaggerConfig {
13
14    @Bean
15    public Docket api() {
16        return new Docket(DocumentationType.SWAGGER_2)
17                .select()
18                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 扫描指定包下的Controller
19                .paths(PathSelectors.any())  // 所有路径
20                .build()
21                .apiInfo(new ApiInfoBuilder()  // API 文档的基本信息
22                        .title("My API Documentation")
23                        .description("Spring Boot with Swagger")
24                        .version("1.0")
25                        .build());
26    }
27}

3. 编写 API 注解

在 Controller 类中，使用 Swagger 提供的注解（如 @Api、@ApiOperation、@ApiParam）来描述 API。

复制
1import org.springframework.web.bind.annotation.*;
2import io.swagger.annotations.Api;
3import io.swagger.annotations.ApiOperation;
4
5@RestController
6@RequestMapping("/api")
7@Api(tags = "User API")  // 为Controller类指定标签
8public class UserController {
9
10    @ApiOperation(value = "获取用户列表", notes = "返回所有用户信息")
11    @GetMapping("/users")
12    public List<User> getUsers() {
13        // 返回用户列表
14        return userService.getUsers();
15    }
16
17    @ApiOperation(value = "获取单个用户", notes = "根据ID获取用户信息")
18    @GetMapping("/users/{id}")
19    public User getUser(@PathVariable("id") Long id) {
20        // 根据ID返回单个用户
21        return userService.getUser(id);
22    }
23}

4. 访问 Swagger UI

启动 Spring Boot 应用后，你可以通过访问 http://localhost:8080/swagger-ui.html 来查看自动生成的 API 文档和交互式界面。

Swagger UI 会显示你的 API 接口，允许你直接在浏览器中测试每个接口。你可以选择请求方法（如 GET、POST、PUT、DELETE），输入请求参数，查看响应结果等。

5. 其他 Swagger 配置（可选）

Swagger 还提供了许多额外的配置选项，比如设置认证、文档信息、API 分组等。

复制
1@Bean
2public Docket api() {
3    return new Docket(DocumentationType.SWAGGER_2)
4            .groupName("v1")
5            .select()
6            .apis(RequestHandlerSelectors.any())
7            .paths(PathSelectors.any())
8            .build()
9            .apiInfo(new ApiInfoBuilder()
10                    .title("API Documentation")
11                    .description("API for User Management")
12                    .version("1.0")
13                    .build());
14}