Swagger/OpenAPI 生成工具 for Java：最佳库

Swagger/OpenAPI 生成工具 for Java：工具完整指南

在现代 Java 开发中，创建高质量的 API 文档已成为流程中不可或缺的一部分。OpenAPI 规范（以前称为 Swagger）提供了一种用于描述 RESTful API 的标准化格式。在本文中，我们将介绍在 Java 项目中生成 Swagger/OpenAPI 文档的主要工具、它们的特点以及使用示例。

什么是 Swagger 和 OpenAPI？

Swagger 是一套用于设计、构建和记录 REST API 的工具。OpenAPI 是一种定义 API 描述标准的规范。Swagger 是该规范最流行的实现。

Java 的主要库

我们来介绍三个关键工具：

• SpringDoc OpenAPI — 用于 Spring Boot 的现代库
• Swagger Core — 来自 Swagger 创建者的基础库
• OpenAPI Generator — 用于生成代码和文档的工具

1. SpringDoc OpenAPI

SpringDoc 是 Spring Boot 项目最流行的选择。它会自动与您的应用程序集成，并根据注解和数据类型生成文档。

安装与配置

在 pom.xml 中添加依赖：

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

使用示例

创建一个带有文档的简单控制器：

@RestController@RequestMapping("/api/users")@Tag(name = "用户", description = "用户管理")public class UserController {

    @GetMapping("/{id}")    @Operation(summary = "根据ID获取用户")    public ResponseEntity<User> getUser(            @Parameter(description = "用户ID")            @PathVariable Long id) {        // 实现        return ResponseEntity.ok(new User(id, "伊万"));    }

    @PostMapping    @Operation(summary = "创建新用户")    public ResponseEntity<User> createUser(            @RequestBody @Valid CreateUserRequest request) {        // 实现        return ResponseEntity.status(201).body(new User(1L, request.getName()));    }}

启动应用程序后，文档可通过地址 http://localhost:8080/swagger-ui.html 访问。

2. Swagger Core

Swagger Core 库提供了一种更底层的方法来创建 OpenAPI 规范。它适用于需要完全控制生成过程的项目。

手动创建规范示例

import io.swagger.v3.oas.models.*;import io.swagger.v3.oas.models.info.*;

OpenAPI openAPI = new OpenAPI()    .info(new Info()        .title("宠物商店 API")        .description("用于管理宠物的 API")        .version("1.0.0")        .contact(new Contact()            .name("开发者")            .email("dev@example.com")))    .addServersItem(new Server()        .url("https://api.example.com/v1")        .description("生产服务器"));

// 添加路径和组件Paths paths = new Paths();paths.addPathItem("/pets", new PathItem()    .get(new Operation()        .operationId("listPets")        .summary("获取宠物列表")));openAPI.setPaths(paths);

3. OpenAPI Generator

OpenAPI Generator 是一个工具，可以根据 OpenAPI 规范生成文档以及客户端/服务器端代码。

在 Maven 中使用

在 pom.