Swagger/OpenAPI 生成工具（Java）：工具概览

Swagger/OpenAPI 生成工具（Java）：库与工具完整概览

现代 Java REST API 开发离不开高质量的文档。OpenAPI 标准（原名 Swagger 规范）已成为描述 HTTP API 的事实行业标准。本文将详细解析 Java 应用中用于生成 OpenAPI 规范的主要库和工具，包括其功能、使用示例及选型标准。

什么是 OpenAPI，为什么需要它？

OpenAPI 是一种规范，用于以 JSON 或 YAML 格式描述 RESTful API。它包含：

端点列表及 HTTP 方法；
数据模型（请求和响应模式）；
参数（query、path、header）；
身份验证和授权信息。

基于 OpenAPI 生成的文档可以自动创建客户端 SDK、进行测试，并保持 API 描述的时效性。Java 生态中有多个成熟的解决方案。

1. SpringDoc OpenAPI（推荐用于 Spring Boot）

SpringDoc 是 Spring 生态中最流行的 OpenAPI 3 生成库。它能自动扫描控制器、@RequestMapping、@GetMapping 等注解，并基于它们构建规范。

依赖配置（Maven）

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

带注解的控制器示例

@RestController@RequestMapping("/api/users")public class UserController {

    @Operation(summary = "根据 ID 获取用户")    @ApiResponses(value = {        @ApiResponse(responseCode = "200", description = "找到用户"),        @ApiResponse(responseCode = "404", description = "未找到用户")    })    @GetMapping("/{id}")    public ResponseEntity<User> getUser(@PathVariable Long id) {        // 业务逻辑        return ResponseEntity.ok(new User(id, "伊万", "ivan@example.com"));    }}

启动应用后，文档可通过 /swagger-ui.html 访问，JSON 格式的规范可通过 /v3/api-docs 获取。

2. Swagger Core（OpenAPI 3.0）

Swagger Core 是由规范创建者提供的底层库。它允许以编程方式构建 OpenAPI 对象，并将其序列化为 JSON/YAML。适用于需要精细控制生成过程的场景。

编程创建规范的示例

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

OpenAPI openAPI = new OpenAPI()    .info(new Info()        .title("示例 API")        .version("1.0.0")        .description("手动创建的文档"))    .path("/hello", new PathItem()        .get(new Operation()            .summary("问候")            .operationId("sayHello")            .addParametersItem(new Parameter()                .name("name")                .in("query")                .required(false)                .schema(new StringSchema()))            .responses(new ApiResponses()                .addApiResponse("200", new ApiResponse()                    .description("OK")                    .content(new Content()                        .addMediaType("text/plain",                             new MediaType().schema(new StringSchema())))))));

// 序列化为 JSONObjectMapper mapper = new ObjectMapper();String json = mapper.writeValueAsString(openAPI);System.out.println(json);