OpenAPI / Swagger Java：方法、示例、安装

什么是 OpenAPI / Swagger，为什么 Java 开发者需要它？

\n\n

OpenAPI（以前称为 Swagger）是一种用于描述、创建、文档化和消费 RESTful API 的规范。对于 Java 开发者来说，OpenAPI / Swagger 库是一个不可或缺的工具，它可以自动化 API 文档化和客户端代码生成的过程。

\n\n

在 Java 项目中使用 OpenAPI / Swagger 的主要原因：

自动生成文档 — 库会分析您的代码（Spring Boot 注解、JAX-RS），并创建 Swagger UI 格式的交互式文档。
标准化 — 统一的 API 描述格式，人和机器都能理解。
生成客户端代码 — 可以为任何用 OpenAPI 描述的 API 生成 Java 客户端。
测试 — Swagger UI 允许您直接从浏览器向 API 发送请求。
与 CI/CD 集成 — 可以在构建阶段检查 API 是否符合规范。

\n\n

在本文中，我们将介绍两个主要的 Java 库：springdoc-openapi（用于 Spring Boot）和 Swagger Core（用于 JAX-RS 和其他框架）。

\n\n

安装 OpenAPI / Swagger 库用于 Java

\n\n

安装取决于所使用的框架。我们来看两个主要选项。

\n\n

选项 1：Spring Boot (springdoc-openapi)

将依赖项添加到您的 pom.xml (Maven)：

<dependency>\n    <groupId>org.springdoc</groupId>\n    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>\n    <version>2.6.0</version>\n</dependency>

\n\n

对于 Gradle (build.gradle)：

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

\n\n

选项 2：JAX-RS / Jakarta (Swagger Core)

Maven：

<dependency>\n    <groupId>io.swagger.core.v3</groupId>\n    <artifactId>swagger-jaxrs2-jakarta</artifactId>\n    <version>2.2.22</version>\n</dependency>

\n\n

Gradle：

implementation 'io.swagger.core.v3:swagger-jaxrs2-jakarta:2.2.22'

\n\n

快速入门：第一个 Spring Boot 示例

\n\n

在 Spring Boot 项目中添加 springdoc-openapi 依赖后，Swagger UI 会自动在 http://localhost:8080/swagger-ui.html 地址可用。让我们创建一个简单的控制器：

\n\n

import io.swagger.v3.oas.annotations.Operation;\nimport io.swagger.v3.oas.annotations.tags.Tag;\nimport org.springframework.web.bind.annotation.*;\n\n@RestController\n@RequestMapping("/api/users")\n@Tag(name = "User Controller", description = "用户管理")\npublic class UserController {\n\n    @GetMapping("/{id}")\n    @Operation(summary = "根据 ID 获取用户")\n    public String getUser(@PathVariable Long id) {\n        return "User with ID: " + id;\n    }\n\n    @PostMapping\n    @Operation(summary = "创建新用户")\n    public String createUser(@RequestBody String userName) {\n        return "Created user: " + userName;\n    }\n}

\n\n

启动应用程序后，打开 http://localhost:8080/swagger-ui.html — 您将看到带有执行请求功能的交互式文档。

\n\n