Spring Boot 与 Swagger 文档生成！

🏆本文收录于「滚雪球学SpringBoot」专栏(全网一个名)，手把手带你零基础入门Spring Boot，从入门到就业，助你早日登顶实现财富自由🚀；同时，欢迎大家关注&&收藏&&订阅！持续更新中，up！up！up！！

环境说明：Windows 10 + IntelliJ IDEA 2021.3.2 + Jdk 1.8

🌟 前言

在现代开发中，API 文档的重要性不言而喻。尤其是在微服务架构中，每个服务提供的 RESTful API 需要清晰的文档来方便其他开发者使用。Swagger 是目前最流行的 API 文档生成工具，它能够自动生成可交互的 API 文档，方便开发者进行接口调试和测试。

本文将深入探讨如何使用 Spring Boot 与 Swagger 自动生成 API 文档，集成 Springfox Swagger，生成 RESTful API 文档，并利用 Swagger UI 进行 API 测试与调试。

🎯 使用 Spring Boot 与 Swagger 自动生成 API 文档

1️⃣ 环境准备

在 Spring Boot 项目中集成 Swagger，最重要的步骤是添加相关的依赖。我们使用 Springfox 作为 Spring Boot 的 Swagger 集成库，它非常简洁且易于配置。

首先，在 pom.xml 文件中添加 Springfox Swagger 相关的依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

这个依赖会为项目引入 Swagger 所需的所有依赖项，包括文档生成工具和 UI 工具。

2️⃣ 配置 Swagger

接下来，我们需要在项目中配置 Swagger 以启用 API 文档生成功能。可以创建一个 SwaggerConfig 配置类，在其中设置生成文档所需的相关信息。

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)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 扫描控制器包
                .paths(PathSelectors.any()) // 设置哪些路径需要生成文档
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("Spring Boot API")
                        .description("Spring Boot 项目的 RESTful API 文档")
                        .version("1.0.0")
                        .build());
    }
}

• @EnableSwagger2 注解启用 Swagger 功能。
• Docket 是 Swagger 的核心配置类，它配置了文档生成的一些基本信息。我们通过 .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) 来指定需要扫描的包，确保只有该包下的控制器会生成文档。
• .paths(PathSelectors.any()) 表示对所有 API 路径都生成文档。你也可以指定某些路径来限制文档生成的范围。

3️⃣ 创建 REST API 控制器

创建一个简单的 API 控制器，供 Swagger 生成文档。控制器中包含两个 GET 请求，一个返回 “Hello” 字符串，另一个返回 “Goodbye” 字符串。

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class ApiController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello, Spring Boot with Swagger!";
    }

    @GetMapping("/goodbye")
    public String goodbye() {
        return "Goodbye, Spring Boot with Swagger!";
    }
}

在这个控制器中，我们定义了两个简单的 API 接口。当你访问 /api/hello 时，返回 "Hello, Spring Boot with Swagger!"；而访问 /api/goodbye 时，返回 "Goodbye, Spring Boot with Swagger!"。

4️⃣ 运行并访问 Swagger 文档

启动 Spring Boot 项目后，访问以下 URL 以查看自动生成的 Swagger 文档：

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

这会打开 Swagger UI 页面，列出所有 API 接口。你将能够看到 ApiController 中定义的 /hello 和 /goodbye 接口，并且 Swagger UI 会自动生成它们的描述、请求参数、返回结果等信息。

⚡ 集成 Spring Boot 与 Springfox Swagger 进行 RESTful API 文档的生成

1️⃣ 添加注解来丰富文档

Swagger 提供了丰富的注解来帮助开发者精确描述 API 的功能和参数。这些注解帮助生成的文档更加详细和易于理解。常用的注解包括：

• @Api: 用于标记类，描述控制器的作用。
• @ApiOperation: 用于标记方法，描述接口操作的功能。
• @ApiParam: 用于方法参数，描述参数的详细信息。

以下是一个使用了 Swagger 注解的控制器示例：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "Greeting API")
@RestController
@RequestMapping("/api")
public class ApiController {

    @ApiOperation(value = "获取问候信息", notes = "根据名字返回问候语")
    @GetMapping("/greet")
    public String greet(
            @ApiParam(value = "用户的名字", required = true) @RequestParam String name) {
        return "Hello, " + name + "!";
    }
}

在这段代码中，我们为 ApiController 类和其中的 greet 方法添加了 Swagger 注解：

• @Api 描述控制器的作用（这里是 “Greeting API”）。
• @ApiOperation 描述 greet 方法的功能，并且提供了一个备注。
• @ApiParam 描述了 name 参数的含义，并且标明它是必需的。

Swagger UI 将根据这些注解自动生成详细的 API 文档。

2️⃣ 支持不同 API 版本的文档

在一些项目中，我们可能需要支持多个版本的 API。Swagger 支持为不同版本的 API 生成独立的文档。你可以通过 Docket 配置多个版本的文档，并通过 groupName 来区分它们。

@Bean
public Docket apiV1() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("v1")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
            .paths(PathSelectors.ant("/v1/**"))
            .build()
            .apiInfo(new ApiInfoBuilder()
                    .title("API V1")
                    .description("API V1 文档")
                    .version("1.0")
                    .build());
}

@Bean
public Docket apiV2() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("v2")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
            .paths(PathSelectors.ant("/v2/**"))
            .build()
            .apiInfo(new ApiInfoBuilder()
                    .title("API V2")
                    .description("API V2 文档")
                    .version("2.0")
                    .build());
}

在这里，我们创建了两个 Docket 实例，一个用于 v1 版本，另一个用于 v2 版本。通过 groupName 属性，我们为不同版本的 API 生成独立的文档。

🔥 使用 Swagger UI 和 Spring Boot 进行 API 测试与调试

1️⃣ 使用 Swagger UI 进行交互式测试

Swagger UI 提供了一个用户友好的界面，允许开发者和测试人员直接在浏览器中执行 API 请求并查看响应。Swagger UI 为每个接口提供了 Try it out 按钮，用户可以输入参数并直接发送请求。

例如，在 /api/greet 接口的文档中，Swagger UI 会显示 name 参数的输入框，用户可以输入一个名字并点击 “Execute” 按钮，Swagger UI 会发送请求并显示返回的结果。

2️⃣ API 安全与授权支持

在实际开发中，API 通常需要安全性配置，例如使用 OAuth 2.0、Basic Auth 或 Token 认证。Swagger 提供了对这些安全机制的支持，可以在生成的文档中添加认证信息。

import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ApiController {

    @ApiOperation(value = "获取用户信息", security = "bearerAuth")
    @GetMapping("/user")
    public String getUser() {
        return "User information";
    }
}

通过 @ApiOperation 注解的 security 属性，Swagger UI 会显示 Bearer Token 输入框，允许用户在测试时提供 Token。

📝 小结

通过本章的学习，我们掌握了如何将 Swagger 集成到 Spring Boot 项目中，并利用 Swagger 自动生成 RESTful API 文档。Swagger 提供了简单易用的注解，可以让我们快速为 API 接口添加描述信息。通过 Swagger UI，我们能够以交互式的方式测试和调试接口，极大提高了开发效率。

🚀 总结

Swagger 是开发 RESTful API 时不可或缺的工具，它不仅能帮助我们自动生成清晰、易懂的 API 文档，还提供了强大的 UI 支持，方便开发者和测试人员进行 API 测试与调试。结合 Spring Boot，Swagger 能够轻松为项目生成文档，并提供交互式测试功能，帮助团队快速理解并使用 API。如果你还没有在项目中使用 Swagger，赶紧动手试一试吧！

🧧福利赠与你🧧

  无论你是计算机专业的学生，还是对编程有兴趣的小伙伴，都建议直接毫无顾忌的学习此专栏「滚雪球学SpringBoot」专栏(全网一个名)，bug菌郑重承诺，凡是学习此专栏的同学，均能获取到所需的知识和技能，全网最快速入门SpringBoot，就像滚雪球一样，越滚越大， 无边无际，指数级提升。

  最后，如果这篇文章对你有所帮助，帮忙给作者来个一键三连，关注、点赞、收藏，您的支持就是我坚持写作最大的动力。

  同时欢迎大家关注公众号:「猿圈奇妙屋」 ，以便学习更多同类型的技术文章，免费白嫖最新BAT互联网公司面试题、4000G pdf电子书籍、简历模板、技术文章Markdown文档等海量资料。

✨️ Who am I?

我是bug菌(全网一个名)，CSDN | 掘金 | InfoQ | 51CTO | 华为云 | 阿里云 | 腾讯云 等社区博客专家，C站博客之星Top30，华为云多年度十佳博主/价值贡献奖，掘金多年度人气作者Top40，掘金等各大社区平台签约作者，51CTO年度博主Top12，掘金/InfoQ/51CTO等社区优质创作者；全网粉丝合计 30w+；更多精彩福利点击这里；硬核微信公众号「猿圈奇妙屋」，欢迎你的加入！免费白嫖最新BAT互联网公司面试真题、4000G PDF电子书籍、简历模板等海量资料，你想要的我都有，关键是你不来拿。

-End-