Java中如何将OpenAPI 2.0转换为OpenAPI 3.0

1. 引言

尽管OpenAPI 3.x规范自2017年发布以来已历经多次更新，但许多API仍在使用旧版本。本文将探讨OpenAPI 2.0与3.0规范之间的核心差异，并学习从旧版本升级到新版本的不同方法。

2. OpenAPI 2.0 vs 3.0对比

简要回顾，OpenAPI为HTTP API提供了人类和机器都可读的标准格式。在3.0版本之前，OpenAPI被称为Swagger规范，是Swagger工具包的一部分。此后，它已成为行业标准，经历了多次更新，带来了诸多改进和新特性。

相比2.0，OpenAPI 3.0引入了多项根本性变化：

✅ 结构调整：新增了components块来组织现有元素（如schemas、responses、parameters）和新元素（如requestBody、examples、headers），提高了复用性
❌ 术语变更：definitions更名为schemas，securityDefinitions更名为securitySchemes
⚠️ JSON Schema增强：新增oneOf、anyOf、not等关键字，支持复杂数据格式的灵活验证
✅ 新特性支持：新增cookie参数、内容协商机制和回调机制，扩展了安全定义并简化了现有流程

完整变更清单请参考官方更新日志。

3. 项目准备

我们通常需要暴露REST服务并使用OpenAPI定义和文档化API。但本文重点是将OpenAPI 2.0规范转换为3.0版本，因此我们使用公开的Swagger Petstore API。

虽然YAML规范也可用，但本文将专注于JSON格式。请下载该文件并放置到项目的resources文件夹中。根据转换方法的不同，我们将通过浏览器、curl上传文件、作为参数传递或在代码中引用它。

4. 工具与库

处理OpenAPI规范时有多种工具和库可选。首先介绍无需本地安装的在线工具，可直接在浏览器中转换API规范版本。

4.1. Swagger Editor

Swagger Editor允许我们上传或粘贴API规范，并将其转换为OpenAPI 3.0或其他格式。提供规范后，从Edit菜单选择Convert to OpenAPI 3，等待转换完成：

转换完成后，新版本规范将自动可用。

4.2. Swagger Converter

Swagger Converter在线版提供两种转换方法：

方法一：直接上传文件或粘贴JSON内容：

curl -X 'POST' \
 'https://converter.swagger.io/api/convert' \
 -H 'accept: application/json' \
 -H 'Content-Type: application/json' \
 --data-binary @swagger.json

方法二：通过URL转换公开API：

curl -X 'GET' \
'https://converter.swagger.io/api/convert?url=https%3A%2F%2Fpetstore.swagger.io%2Fv2%2Fswagger.json' \
-H 'accept: application/json'

该工具支持JSON和YAML格式，并提供用户友好界面。

4.3. API Spec Converter

对于公开API，另一个选择是开源库api-spec-converter。提供URL后，选择OpenAPI 2 (Swagger)作为源格式，OpenAPI 3.0作为目标格式，点击Convert：

转换成功后可下载新规范。

4.4. Swagger Codegen

Swagger Codegen是开源代码生成器。除创建REST客户端、生成服务端存根和API文档外，还可用于转换规范。

下载最新版本后执行：

java -jar swagger-codegen-cli-3.0.62.jar generate \
  -l openapi \
  -i https://petstore.swagger.io/v2/swagger.json \
  -o converted

转换结果将保存在指定输出目录（本例为converted）。通过设置不同参数可自定义输出格式：

-l openapi：生成JSON格式
-l openapi-yaml：生成YAML格式

4.5. OpenAPI Generator

OpenAPI Generator作为Swagger Codegen的分支，转换过程类似。使用最新版本执行：

java -jar openapi-generator-cli-7.9.0.jar generate \
  -g openapi \
  -i https://petstore.swagger.io/v2/swagger.json \
  -o converted

通过选择不同的生成器名称（-g）可控制输出格式：

-g openapi：生成JSON
-g openapi-yaml：生成YAML

⚠️ 注意：运行JAR文件时需确保Java版本兼容，否则可能遇到UnsupportedClassVersionError错误。

4.6. Swagger Parser

顾名思义，Swagger Parser用于解析OpenAPI文档，同时也能将旧版规范转换为新版本。

参考Swagger Parser使用指南，创建规范处理方法：

private static OpenAPI processSpecificationJson(final String specificationFileLocation) {
    SwaggerParseResult result = new OpenAPIParser().readLocation(specificationFileLocation, null, null);

    final OpenAPI openAPI = result.getOpenAPI();
    if (openAPI == null) {
        throw new IllegalArgumentException("Failed to parse OpenAPI specification from: " 
          + specificationFileLocation);
    }

    return openAPI;
}

使用ObjectMapper将OpenAPI对象序列化为JSON：

private static String asJsonString(OpenAPI openAPI) throws JsonProcessingException {
    return objectMapper.writerWithDefaultPrettyPrinter()
      .writeValueAsString(openAPI);
}

配置ObjectMapper使JSON输出更易读并排除null值：

private static final ObjectMapper objectMapper;

static {
    objectMapper = new ObjectMapper();
    objectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
}

定义转换方法：

public static String convert(String specificationFileLocation) throws IOException {
    if (specificationFileLocation == null || specificationFileLocation.isEmpty()) {
        throw new IllegalArgumentException("Specification file path cannot be null or empty.");
    }

    return asJsonString(processSpecificationJson(specificationFileLocation));
}

测试验证转换结果：

@Test
void givenOpenApi2_whenConvert_thenSpecificationSuccessfullyConverted() throws IOException {
    String openAPI3 = SwaggerToOpenApiConverter.convert(FILE_OPEN_API_2_SPECIFICATION);

    assertNotNull(openAPI3);
}

测试通过即表示转换成功。

5. 总结

本文展示了将OpenAPI 2.0规范转换为3.0的多种方案，包括在线工具（Swagger Editor/Converter）和命令行工具（Swagger Codegen/OpenAPI Generator），以及编程方式（Swagger Parser）。

选择哪种方案取决于：

API是否公开可访问
对工具的熟悉程度
需要实现的额外功能

这些工具转换功能相似，但各有特点，可根据实际需求灵活选用。

Persistence

REST

Security