Swagger 配置指南——快速构建 API 文档

在现代 Web 开发中，API 文档是前后端协作的重要桥梁。Swagger 是一个强大的工具，可以帮助我们自动生成 API 文档，并提供交互式的 API 测试界面。本文将详细介绍如何在 Spring Boot 项目中配置 Swagger，并生成美观且实用的 API 文档。

---

1. Swagger 简介

Swagger 是一套围绕 OpenAPI 规范构建的工具，用于设计、构建、记录和使用 RESTful API。通过 Swagger，开发者可以：

• 自动生成 API 文档。
• 提供交互式的 API 测试界面。
• 支持多种语言和框架（如 Java、Python、Node.js 等）。

---

2. Spring Boot 集成 Swagger

2.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>

• springfox-swagger2：核心库，用于生成 API 文档。
• springfox-swagger-ui：提供交互式的 API 测试界面。

---

2.2 配置 Swagger

在 Spring Boot 项目中，创建一个配置类来启用 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.demo.controller")) // 指定扫描的包
                .paths(PathSelectors.any())
                .build();
    }
}

• @EnableSwagger2：启用 Swagger。
• Docket：配置 Swagger 的核心 Bean。
• apiInfo：设置 API 文档的基本信息，如标题、描述、版本等。
• apis：指定扫描的控制器包路径。
• paths：指定需要生成文档的 API 路径。

---

2.3 启动项目并访问 Swagger UI

启动 Spring Boot 项目后，访问以下 URL 即可查看 Swagger UI：

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

• Swagger UI：提供交互式的 API 测试界面，支持在线测试 API。

---

3. Swagger 注解详解

Swagger 提供了一系列注解，用于增强 API 文档的可读性和实用性。

3.1 @Api

• 作用：标注在控制器类上，用于描述整个控制器。

• 示例 ：

  @Api(tags = "用户管理")
  @RestController
  @RequestMapping("/user")
  public class UserController {
      // ...
  }

3.2 @ApiOperation

• 作用：标注在方法上，用于描述 API 的功能。

• 示例 ：

  @ApiOperation(value = "获取用户信息", notes = "根据用户 ID 获取用户信息")
  @GetMapping("/{id}")
  public User getUser(@PathVariable Long id) {
      // ...
  }

3.3 @ApiParam

• 作用：标注在方法参数上，用于描述参数的含义。

• 示例 ：

  @ApiOperation(value = "更新用户信息")
  @PutMapping("/{id}")
  public void updateUser(
          @ApiParam(value = "用户 ID", required = true) @PathVariable Long id,
          @ApiParam(value = "用户信息", required = true) @RequestBody User user) {
      // ...
  }

3.4 @ApiModel 和 @ApiModelProperty

• 作用：标注在实体类上，用于描述模型及其属性。

• 示例 ：

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

---

4. Swagger 高级配置

4.1 分组配置

如果项目中有多个模块，可以为每个模块配置不同的 Swagger 分组：

@Bean
public Docket userApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("用户管理")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.user"))
            .paths(PathSelectors.any())
            .build();
}

@Bean
public Docket orderApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("订单管理")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.order"))
            .paths(PathSelectors.any())
            .build();
}

4.2 全局参数配置

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

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .globalOperationParameters(Collections.singletonList(
                    new ParameterBuilder()
                            .name("Authorization")
                            .description("访问令牌")
                            .modelRef(new ModelRef("string"))
                            .parameterType("header")
                            .required(false)
                            .build()
            ))
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
            .paths(PathSelectors.any())
            .build();
}

---

5. 总结

通过 Swagger，我们可以快速生成美观且实用的 API 文档，并支持在线测试 API。本文详细介绍了如何在 Spring Boot 项目中配置 Swagger，并讲解了常用的 Swagger 注解和高级配置。希望本文能帮助你更好地使用 Swagger，提升开发效率！