打造美观 API 文档：Spring Boot + Swagger 实战指南

打造美观 API 文档：Spring Boot + Swagger 实战指南

导语

在现代 Web 开发中，API 文档是开发者和团队协作的重要组成部分。Swagger 作为一款强大的 API 文档生成工具，能够自动生成直观、可交互的接口文档，提升开发效率。本文将详细介绍如何在 Spring Boot 2 和 Spring Boot 3 中集成 Swagger，并展示多种接口文档风格，帮助开发者选择适合自己项目的展示方式。

---

一、Swagger 简介

Swagger 是一个开源工具，用于生成、描述和可视化 RESTful API。它不仅能自动生成 API 文档，还提供交互式界面，方便开发者测试和调试接口。Swagger 与 Spring Boot 集成后，可以轻松管理和展示项目的 API。

---

二、Spring Boot 2 集成 Swagger

Spring Boot 2 中，常用的 Swagger 集成方案是基于 Springfox 库。以下是具体步骤：

1. 添加依赖

在项目的 pom.xml 文件中添加以下依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. 配置 Swagger

创建一个配置类，例如 SwaggerConfig.java，启用 Swagger 并定义文档的基本信息：

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public 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("Spring Boot 2 Swagger API")
                .description("API documentation for Spring Boot 2 project")
                .version("1.0.0")
                .build();
    }
}

3. 访问 Swagger UI

启动 Spring Boot 应用后，打开浏览器访问 http://localhost:8080/swagger-ui.html，即可看到生成的 API 文档界面。

---

三、Spring Boot 3 集成 Swagger

Spring Boot 3 中，由于 Springfox 已不再积极维护，推荐使用 Springdoc OpenAPI 库。它与 Spring Boot 3 的新特性（如 Jakarta EE）兼容，且配置更简单。

1. 添加依赖

在 pom.xml 中添加 Springdoc OpenAPI 的依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.9</version>
</dependency>

2. 配置 Swagger

Springdoc 默认自动启用 Swagger UI，无需额外配置。但可以通过 application.properties 或 application.yml 自定义路径和行为，例如：

# 自定义 Swagger UI 路径
springdoc.swagger-ui.path=/swagger-ui.html
# 自定义 API 文档 JSON 路径
springdoc.api-docs.path=/v3/api-docs

3. 访问 Swagger UI

启动应用后，访问 http://localhost:8080/swagger-ui.html，即可查看 API 文档。

---

四、多种接口文档风格展示

Swagger 提供了多种 UI 风格，开发者可以根据需求选择合适的展示方式。以下是几种常见的风格及其配置方法：

1. 默认 Swagger UI

Swagger UI 是最常用的风格，提供交互式界面，支持 API 测试。Spring Boot 2 和 3 默认集成后即可使用：

• Spring Boot 2：http://localhost:8080/swagger-ui.html
• Spring Boot 3：http://localhost:8080/swagger-ui.html

2. Redoc

Redoc 是一个简洁、美观的静态文档展示工具，适合生成静态 API 文档。在 Spring Boot 3 中使用 Springdoc 配置：

在 application.properties 中添加：

# 禁用默认 Swagger UI
springdoc.swagger-ui.enabled=false
# 启用 Redoc
springdoc.redoc.enabled=true

访问 http://localhost:8080/redoc，即可查看 Redoc 风格的文档。

3. Knife4j

Knife4j 是 Swagger 的增强版，提供更丰富的功能和更友好的界面，支持 Spring Boot 2 和 3。

在 Spring Boot 2 中集成 Knife4j

添加依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

修改配置类：

@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfig {
    @Bean
    public 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("Spring Boot 2 Knife4j API")
                .description("API documentation with Knife4j")
                .version("1.0.0")
                .build();
    }
}

访问 http://localhost:8080/doc.html，即可体验 Knife4j 界面。

在 Spring Boot 3 中集成 Knife4j

添加依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

无需额外配置，启动应用后访问 http://localhost:8080/doc.html。

---

五、实战示例

以下是一个简单的 Spring Boot 项目示例，展示如何使用 Swagger 注解生成详细的 API 文档。

1. 创建控制器

创建一个简单的 REST 控制器：

import org.springframework.web.bind.annotation.*;
import java.util.*;

@RestController
@RequestMapping("/api")
public class UserController {
    @GetMapping("/users")
    public List<String> getUsers() {
        return Arrays.asList("Alice", "Bob");
    }

    @PostMapping("/users")
    public String createUser(@RequestBody String user) {
        return "Created: " + user;
    }
}

2. 添加 Swagger 注解

为控制器和方法添加注解，提供更详细的 API 描述：

Spring Boot 2（Springfox）

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.*;

@Api(tags = "User API")
@RestController
@RequestMapping("/api")
public class UserController {
    @ApiOperation(value = "获取所有用户", notes = "返回用户列表")
    @GetMapping("/users")
    public List<String> getUsers() {
        return Arrays.asList("Alice", "Bob");
    }

    @ApiOperation(value = "创建新用户", notes = "创建并返回新用户")
    @PostMapping("/users")
    public String createUser(@RequestBody String user) {
        return "Created: " + user;
    }
}

Spring Boot 3（Springdoc）

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;
import java.util.*;

@Tag(name = "User API")
@RestController
@RequestMapping("/api")
public class UserController {
    @Operation(summary = "获取所有用户", description = "返回用户列表")
    @GetMapping("/users")
    public List<String> getUsers() {
        return Arrays.asList("Alice", "Bob");
    }

    @Operation(summary = "创建新用户", description = "创建并返回新用户")
    @PostMapping("/users")
    public String createUser(@RequestBody String user) {
        return "Created: " + user;
    }
}

3. 访问和测试

启动应用后，访问对应的 Swagger UI 或 Knife4j 地址（如 http://localhost:8080/swagger-ui.html 或 http://localhost:8080/doc.html），即可查看并测试 API。

---

六、总结

本文介绍了在 Spring Boot 2 和 Spring Boot 3 中集成 Swagger 的实战步骤：

• Spring Boot 2 使用 Springfox Swagger，配置简单但维护较少。
• Spring Boot 3 推荐 Springdoc OpenAPI，与新版本兼容且功能强大。

同时展示了多种接口文档风格：

• Swagger UI：交互性强，适合开发和调试。
• Redoc：简洁美观，适合静态文档。
• Knife4j：功能丰富，体验更优。

通过实战示例，开发者可以快速上手并将 Swagger 应用到自己的项目中，提升 API 管理的效率和质量。

---

参考资料

• Springfox Swagger 官方文档
• Springdoc OpenAPI 官方文档
• Knife4j 官方文档