如何序列化Swagger-Parser的OpenAPI对象以兼容解析工具？

问题背景 #

我需要构建一套流程：读取外部系统生成的OpenAPI规范文件，修改后适配Spring API，再将修改后的内容写入文件，供openapi-generator生成API和Model类。

我用swagger-parser读取原始文件并修改OpenAPI对象，但用Json.pretty()序列化后，openapi-generator解析时出现多个验证错误：

• Schema同时包含type（字符串）和types（字符串数组）属性
• 扩展字段（如x-whatever）被渲染在extensions对象内部而非直接作为顶级字段
• OpenAPI对象的内部额外字段被写入JSON

我的代码大致如下：

SwaggerParseResult result = new OpenAPIParser().readLocation( INPUT_FILE, null, null );
OpenAPI openAPI = result.getOpenAPI();

// 修改API描述的逻辑...

String rawData = Json.pretty(openAPI);
try {
  FileUtils.writeStringToFile( OUTPUT_FILE, rawData, Charset.defaultCharset() );
} catch (IOException e) {
  throw new RuntimeException("Error writing file", e);
}

错误的JSON示例：

"components" : {
  "schemas" : {
    "something" : {
      "minLength" : 1,
      "maxLength" : 10,
      "type" : "string",
      "types" : [ "string" ],
      "extensions" : {
        "x-whatever" : true
      }
    }
  }
}

尝试过自定义ObjectMapper加mixins，但过程太复杂，想找更简单的解决方案。

解决方案 #

直接使用swagger-core官方提供的序列化工具，这些工具已经内置了处理OpenAPI规范的逻辑，能自动过滤不符合规范的字段、正确序列化扩展字段：

方法1：使用官方的Json.prettyPrint()方法 #

替换原来的Json.pretty()为Json.prettyPrint()，这个方法会应用正确的序列化配置：

import io.swagger.v3.core.util.Json;

// ... 修改OpenAPI对象的逻辑 ...

String prettyJson = Json.prettyPrint(openAPI);
try {
  FileUtils.writeStringToFile(OUTPUT_FILE, prettyJson, Charset.defaultCharset());
} catch (IOException e) {
  throw new RuntimeException("Error writing file", e);
}

方法2：使用官方配置的ObjectMapper #

如果需要更灵活的序列化控制，可以直接获取官方预配置的ObjectMapper实例：

import com.fasterxml.jackson.databind.ObjectMapper;
import io.swagger.v3.core.util.Json;

// ... 修改OpenAPI对象的逻辑 ...

ObjectMapper swaggerMapper = Json.mapper();
String prettyJson = swaggerMapper.writerWithDefaultPrettyPrinter()
                                 .writeValueAsString(openAPI);
// 写入文件逻辑同上

方法3：若使用YAML格式 #

如果需要输出YAML文件，用Yaml类的对应方法即可：

import io.swagger.v3.core.util.Yaml;

String prettyYaml = Yaml.prettyPrint(openAPI);
// 写入文件

原理说明 #

swagger-core提供的Json和Yaml工具类，内部已经配置了专门的ObjectMapper，包含：

• 过滤OpenAPI对象内部的非规范字段（如types）
• 将extensions中的键值对直接序列化为x-*形式的顶级字段
• 遵循OpenAPI 3.0规范的序列化规则，确保输出的文件能被openapi-generator和Swagger自身的解析器正确识别

内容的提问来源于stack exchange，提问作者jpappe