本文由 简悦 SimpRead 转码， 原文地址 blog.csdn.net
本文将详细介绍如何在 Spring Boot 应用程序中集成 Swagger3，以构建现代化的 RESTful API 文档。我们将探讨 Swagger3 的基本概念，以及如何使用 Spring Boot 和 Swagger3 库来实现 API 文档。此外，我们将通过具体的示例来展示如何在 Spring Boot 中配置和使用 Swagger3。本文适合希望使用 Swagger3 为 Spring Boot 应用程序生成 API 文档的开发者阅读。
一、引言
在现代 Web 开发中，RESTful API 文档是一个重要的组成部分。Swagger 是一个流行的 API 框架，用于构建、描述、消费 RESTful 服务。Swagger3 是 Swagger 的下一代，它提供了更简洁、更强大的功能，以满足现代 API 的需求。Spring Boot 提供了对 Swagger3 的直接支持，使得集成和使用 Swagger3 变得非常简单。
二、Swagger3 的基本概念
1. 什么是 Swagger3？
Swagger3 是一个用于构建、描述、消费 RESTful 服务的框架。它提供了一套完整的工具，用于生成 API 文档、自动生成客户端 SDK、进行 API 测试等。Swagger3 支持 OpenAPI 3.0 规范，使得 API 文档更加丰富和交互式。
2. Swagger3 的特点
- 现代化：Swagger3 提供了更加简洁、现代的 API 文档界面。
- 交互式：Swagger3 支持交互式 API 测试，用户可以在线发送请求和查看响应。
- 可扩展性：Swagger3 支持多种插件和扩展，以满足不同的需求。
- 社区支持：Swagger3 拥有一个庞大的社区，提供了丰富的资源和工具。
三、在 Spring Boot 中集成 Swagger3
1. 添加 Swagger3 依赖
在项目的 pom.xml 文件中，添加 Spring Boot 的 Swagger3 依赖：
<dependencies>
<!-- Spring Boot Web依赖 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Spring Boot OpenAPI依赖 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-openapi</artifactId>
<version>3.0.0</version>
</dependency>
</dependencies>
2. 配置 Swagger3
Spring Boot 会自动配置 Swagger3，但我们可以通过在 application.properties 或 application.yml 文件中添加一些属性来定制 Swagger3 的行为。例如：
# application.properties
spring.mvc.static-path-pattern=/static/**
3. 创建 Swagger3 配置类
虽然 Spring Boot 会自动配置 Swagger3，但我们也可以通过创建一个 Swagger3 配置类来进一步定制 Swagger3 的行为。以下是一个简单的 Swagger3 配置类示例：
package com.example.demo.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
@EnableOpenApi
public class SwaggerConfig {
@Bean
public Docket apiDocket() {
return new Docket(DocumentationType.OAS_30)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build();
}
}
在上面的代码中，我们创建了一个 Docket Bean，用于配置 Swagger3 的文档类型为 OAS 3.0，并选择 com.example.demo.controller 包下的 API 进行文档生成。
4. 创建 Controller 类
在 Spring Boot 项目中创建一个 Controller 类，用于提供 RESTful API。以下是一个简单的 Controller 类示例：
package com.example.demo.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class SampleController {
@GetMapping("/hello")
public String hello() {
return "Hello, World!";
}
}
5. 运行项目
将以上代码添加到我们的 Spring Boot 项目中，并运行项目。我们可以通过浏览器或 Postman 等工具访问http://localhost:8080/swagger-ui/，观察 Swagger3 UI 界面的渲染效果。
四、Swagger3 的高级用法
1. 添加 API 信息
Swagger3 允许您添加 API 信息，如标题、描述、版本等。我们可以在 Swagger3 配置类中添加以下代码来设置 API 信息：
@Bean
public Docket apiDocket() {
return new Docket(DocumentationType.OAS_30)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot + Swagger3 API Documentation")
.description("This is the API documentation for the Spring Boot application.")
.version("1.0.0")
.build();
}
2. 添加分组
Swagger3 支持为 API 文档添加分组，以便更好地组织和管理 API。我们可以在 Swagger3 配置类中添加以下代码来设置分组：
@Bean
public Docket apiDocket() {
return new Docket(DocumentationType.OAS_30)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.groupName("sample-group")
.build()
.apiInfo(apiInfo());
}
3. 添加响应示例
Swagger3 允许您为 API 响应添加示例，以便用户更好地理解 API 的返回值。我们可以在 Swagger3 配置类中添加以下代码来设置响应示例：
@Bean
public Docket apiDocket() {
return new Docket(DocumentationType.OAS_30)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo())
.globalResponses(HttpMethod.GET, responseListBuilder -> responseListBuilder
.addResponse(HttpStatus.OK.value(), "success", new ObjectMapper().writeValueAsString(new SampleResponse())));
}
private class SampleResponse {
private String status;
private String message;
// getter和setter方法
}
五、总结
本文详细介绍了如何在 Spring Boot 应用程序中集成 Swagger3，以构建现代化的 RESTful API 文档。我们首先了解了 Swagger3 的基本概念和特点。然后，我们学习了如何使用 Spring Boot 和 Swagger3 库来实现 API 文档，并通过具体的示例展示了如何在 Spring Boot 中配置和使用 Swagger3。
通过本文，我们应该已经掌握了如何在 Spring Boot 中集成和使用 Swagger3 来生成 API 文档。我们学会了如何配置 Swagger3，如何为 API 添加信息、分组和响应示例。希望本文能够帮助您在开发 Spring Boot 应用程序时更加得心应手。如果您有任何疑问或建议，请随时留言交流。