如何以编程方式编辑 java 中的 swagger yaml 文件以将请求参数添加到 REST 端点？

Question

我有一个包含 5000 多行的第三方库提供的 yaml 文件。

那个yaml文件需要读取，然后需要添加一个查询参数“status”
带有路径/path/to/api的 REST 端点，用于非GET方法。

编辑 1：我没有类文件或 POJO。 这是一个招摇的yaml。

我看过 SwaggerParser，但我看到很多代码片段用于读取 yaml 文件，但没有添加到其中。

Answer 1

正如您正确指出的，您可以使用Swagger Parser来修改 OpenAPI/Swagger 定义。

请注意（截至 2019 年 7 月）有 2 个版本的 Swagger Parser，它们使用的包名和类名略有不同：

• Swagger Parser 2.0 ( io.swagger.v3.parser.OpenAPIV3Parser ) – 读取 Swagger 1.x、Swagger 2.0 和 OpenAPI 3.0 格式并写入 OpenAPI 3.0 。

• Swagger Parser 1.x ( io.swagger.parser.SwaggerParser ) – 读取 Swagger 1.x 和 Swagger 2.0 格式并写入 Swagger 2.0 。

由于您的定义是 Swagger 2.0，我假设您希望保持原样，因此您需要 Swagger Parser 1.x 。

以下是添加新参数的方法：

import io.swagger.parser.SwaggerParser;
import io.swagger.models.Swagger;
import io.swagger.models.Operation;
import io.swagger.models.HttpMethod;
import io.swagger.models.parameters.QueryParameter;
import io.swagger.util.Yaml;
import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
import com.fasterxml.jackson.dataformat.yaml.YAMLGenerator;
import org.apache.commons.io.FileUtils;
import java.io.File;
import java.util.Map;
...

Swagger swagger = new SwaggerParser().read("https://petstore.swagger.io/v2/swagger.json");

// Configure the "status" query parameter
QueryParameter status = new QueryParameter();
status.setName("status");
status.setType("string");
// You can also setDescription, setRequired, setExample, etc. as needed

// Get all HTTP methods for the "/pet/{petId}" path
Map<HttpMethod, Operation> operations = swagger.getPaths().get("/pet/{petId}").getOperationMap();

// Add the "status" parameter to non-GET methods only
for (Map.Entry<HttpMethod, Operation> op : operations.entrySet()){
    if (op.getKey() != HttpMethod.GET) {
        // TODO: Check if this operation already has
        // a query parameter named "status"

        op.getValue().addParameter(status);
    }
}

// Save the new file
try {
    // (Optional) Configure YAML formatter
    YAMLFactory factory = (YAMLFactory) Yaml.mapper().getFactory();
    factory.disable(YAMLGenerator.Feature.WRITE_DOC_START_MARKER)
        .enable(YAMLGenerator.Feature.MINIMIZE_QUOTES)
        .enable(YAMLGenerator.Feature.ALWAYS_QUOTE_NUMBERS_AS_STRINGS);

    String yaml = Yaml.pretty().writeValueAsString(swagger);
    FileUtils.writeStringToFile(new File("C:\\Work\\petstore-modified.yaml"), yaml);
}
catch (Exception e) {
    e.printStackTrace();
}

此示例假定所有路径和参数都是内联定义的（无 $refs）。 根据实际 API 定义的结构，您可能需要更新代码以正确处理：

• 被$引用的路径

  paths: /something: $ref: './pathitems/something.yaml'

• 与要添加的参数同名的现有路径级参数

  paths: /something: parameters: - in: query name: status type: string

• $ref'erenced 而不是内联定义的具有相同名称的现有参数

  paths: /something: parameters: - $ref: '#/definitions/statusQueryParam' /something2: post: parameters: - $ref: '#/definitions/statusQueryParam' parameters: statusQueryParam: in: query name: status type: string

• 等等。

Answer 2

我会尝试使用 Jackson 库来处理 yaml 文件，因为它们都具有读取和写入 api 的功能（用法就像 json）。

// Create an ObjectMapper mapper for YAML
ObjectMapper mapper = new ObjectMapper(new YAMLFactory());

Map config = mapper.readValue(new File("src/main/resources/orderInput.yaml"), Map.class);

//modify your class as needed here
((Map) config.get("rest")).put("your/changes/here")

// Write object as YAML file
mapper.writeValue(new File("/path/to/yaml/file"), yourClass);
Alternatively you can write your object as a string:

// Write object as YAML string
String yaml = mapper.writeValueAsString(example);  

有关更多信息，请参阅以下主题。
使用 Jackson 将 Java 对象实例写入 YAML

编辑：基于问题编辑，我稍微修改了答案，而不是将文件解包到 pojo/class 中，我会使用 Map 将其转换为 ，对其进行必要的编辑并将其写回。 另一种更安全的方法是执行 objectMapper.readTree() ，它返回一个 JsonNode，修改节点，然后将其推回