SpringBoot 3.x中的Swagger与OpenAPI集成！

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

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

前言

在现代应用开发中，文档的生成和管理是开发工作中的一大挑战。尤其是在微服务架构和API驱动的开发中，如何让API文档始终与代码同步，并且易于理解和操作，已经成为了开发者关注的重点。Swagger和OpenAPI作为当前最流行的API文档生成工具，提供了一个标准化的方式来描述和管理API。今天，我们将一起学习如何在Spring Boot 3.x中集成Swagger与OpenAPI，自动生成Swagger文档，并实现交互式文档展示！🎯

目录 📚

• 🎯 前言：Swagger与OpenAPI的重要性
• 🔧 Swagger与OpenAPI的关系
• 🛠️ 在Spring Boot项目中集成Swagger
• ⚙️ 配置与定制Swagger文档
• 📝 集成Swagger UI进行交互式API文档
• 📑 总结：高效生成与展示API文档

🎯 前言：Swagger与OpenAPI的重要性 💡

在API驱动的开发中，API文档的管理与生成至关重要。无论是开发者、测试人员，还是前端工程师，良好的API文档能够帮助团队快速了解和调用API，从而提高工作效率。Swagger与OpenAPI作为最广泛使用的API文档生成工具，不仅能够自动生成API文档，还能提供交互式UI，方便测试和调试。

OpenAPI是Swagger的进化版本，它提供了一个更加标准化的API描述方式，支持生成可交互的文档和客户端代码。Spring Boot通过Springdoc OpenAPI库，使得在Spring Boot项目中集成Swagger和OpenAPI变得更加简单。

今天，我们将介绍如何使用Springdoc OpenAPI在Spring Boot 3.x项目中集成Swagger，自动生成API文档，并定制API描述和参数，同时集成Swagger UI进行交互式API文档展示。🎉

🔧 Swagger与OpenAPI的关系 🌍

💡 Swagger

Swagger最初是一个API文档生成工具，通过注解来描述RESTful API，并自动生成文档。它提供了便捷的API描述、自动生成文档和交互式UI等功能，使得开发者可以更快速地创建和管理API文档。

🌍 OpenAPI

OpenAPI是Swagger的继任者，提出了一种开放的、标准化的API描述格式。OpenAPI 规范基于Swagger规范，并扩展了其功能，现在它已成为API文档生成的行业标准。OpenAPI规范提供了更多的功能，如API版本控制、组件重用等。

🔄 Swagger与OpenAPI的关系

OpenAPI 3.x 是 Swagger 2.x 的升级版本，Swagger 2.x 主要支持旧版的API文档生成，而OpenAPI 3.x 采用了更加模块化和标准化的方式，适应更复杂的场景。Springdoc OpenAPI 支持OpenAPI 3.x规范，并可以与Spring Boot无缝集成。

🛠️ 在Spring Boot项目中集成Swagger 🚀

步骤 1：添加Springdoc OpenAPI依赖

首先，我们需要在Spring Boot项目中引入Springdoc OpenAPI的依赖。我们可以通过Maven或Gradle来添加依赖。

Maven依赖

在pom.xml中添加如下依赖：

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

Gradle依赖

如果是使用Gradle，可以添加以下依赖：

dependencies {
    implementation 'org.springdoc:springdoc-openapi-ui:1.6.0'
}

步骤 2：启用OpenAPI配置

Springdoc OpenAPI会自动配置，但如果你需要进一步定制API文档的设置，可以在配置类中进行额外配置。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springdoc.core.GroupedOpenApi;

@Configuration
public class OpenApiConfig {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public")
                .packagesToScan("com.example.controller")
                .build();
    }
}

在上述配置中，publicApi()方法定义了一个名为public的API组，它将扫描com.example.controller包下的所有Controller类，并为其生成API文档。

步骤 3：访问Swagger UI

完成上述步骤后，启动Spring Boot应用并访问 http://localhost:8080/swagger-ui.html，你将看到自动生成的Swagger UI界面，所有API接口都会自动列出，并且支持交互式测试。

⚙️ 配置与定制Swagger文档 📝

我们可以通过一些注解和配置来定制生成的Swagger文档，具体来说包括：API描述、路径参数、响应类型等。

🚨 自定义API描述

我们可以使用@OpenAPIDefinition、@Info等注解来为API文档添加描述信息。

import org.springdoc.core.annotations.OpenAPIDefinition;
import org.springdoc.core.annotations.Info;
import org.springframework.context.annotation.Configuration;

@OpenAPIDefinition(
    info = @Info(
            title = "API文档",
            version = "v1",
            description = "这是一个示例API文档"
    )
)
@Configuration
public class SwaggerConfig {
}

🚨 自定义API参数描述

在Controller层，我们可以通过@Parameter注解来为API的输入参数添加描述信息。

import io.swagger.v3.oas.annotations.Parameter;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @GetMapping("/users")
    public String getUserById(
        @Parameter(description = "用户ID", required = true) 
        @RequestParam String userId) {
        return "User info for: " + userId;
    }
}

🚨 自定义响应描述

同样，我们可以通过@ApiResponse注解来为API的响应结果添加描述。

import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "请求成功"),
    @ApiResponse(responseCode = "404", description = "未找到用户")
})
@GetMapping("/users/{userId}")
public String getUserById(@PathVariable String userId) {
    return "User info for: " + userId;
}

📝 集成Swagger UI进行交互式API文档 🎨

Swagger UI 是一个交互式文档界面，允许开发者在浏览器中直接进行API的调用和测试。Springdoc OpenAPI默认集成了Swagger UI，因此只需要在应用中添加相关依赖并配置即可自动启用Swagger UI。

默认访问路径

Swagger UI 的默认访问路径为 http://localhost:8080/swagger-ui.html。在该界面中，开发者可以查看所有API接口的详细信息，包括请求方法、参数、响应等，并且可以直接发送请求测试API接口。

配置Swagger UI路径

如果需要修改Swagger UI的访问路径，可以通过如下配置进行定制：

springdoc.swagger-ui.path=/docs

通过上述配置，Swagger UI的访问路径将变为 http://localhost:8080/docs。

📑 总结：高效生成与展示API文档 🚀

通过集成Springdoc OpenAPI，我们能够轻松地在Spring Boot项目中生成Swagger文档。它不仅支持自动生成API文档，还允许开发者定制API的描述、参数、响应等信息，并通过Swagger UI提供交互式文档，方便进行API调试和测试。

自定义API描述、参数注解以及响应描述，进一步提升了Swagger文档的可读性和易用性。通过集成Swagger UI，我们能够为团队成员提供一个清晰、易用的API交互界面，进一步提高开发效率。

希望今天的分享能帮助大家在Spring Boot项目中高效集成Swagger与OpenAPI，轻松生成和管理API文档！🎉

如果有任何问题，欢迎随时讨论！💬

🧧福利赠与你🧧

  无论你是计算机专业的学生，还是对编程有兴趣的小伙伴，都建议直接毫无顾忌的学习此专栏「滚雪球学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-