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

目录

• 打造美观 API 文档：Spring Boot + Swagger 实战指南
• • 导语
  • 一、Swagger 简介
  • 二、Spring Boot 2 集成 Swagger
  • • 1. 添加依赖
    • 2. 配置 Swagger
    • 3. 访问 Swagger UI
    • 三、Spring Boot 3 集成 Swagger
    • • 1. 添加依赖
      • 2. 配置 Swagger
      • 3. 访问 Swagger UI
      • 四、多种接口文档风格展示
      • • 1. 默认 Swagger UI
        • 2. Redoc
        • 3. Knife4j
        • • 在 Spring Boot 2 中集成 Knife4j
          • 在 Spring Boot 3 中集成 Knife4j
          • 五、实战示例
          • • 1. 创建控制器
            • 2. 添加 Swagger 注解
            • • Spring Boot 2（Springfox）
              • Spring Boot 3（Springdoc）
              • 3. 访问和测试
              • 六、总结
              • 参考资料

                打造美观 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 文件中添加以下依赖：

                    io.springfox
                    springfox-swagger2
                    2.9.2
                
                
                    io.springfox
                    springfox-swagger-ui
                    2.9.2
                
                

                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 的依赖：

                    org.springdoc
                    springdoc-openapi-ui
                    1.6.9
                
                

                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

                  添加依赖：

                  
                  （图片来源网络，侵删）

                      com.github.xiaoymin
                      knife4j-spring-boot-starter
                      2.0.9
                  
                  

                  修改配置类：

                  @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

                  添加依赖：

                      com.github.xiaoymin
                      knife4j-openapi3-spring-boot-starter
                      3.0.3
                  
                  

                  无需额外配置，启动应用后访问 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 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 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 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 官方文档