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

Question

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

需要读取该 yaml 文件，然后需要将查询参数“status”添加到路径为/path/to/api 的
REST 端点（对于非GET方法）。

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

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

Answer 1

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

\n\n

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

\n\n

\n

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

\n

• Swagger 解析器 1.x ( io.swagger.parser.SwaggerParser) \xe2\x80\x93 读取 Swagger 1.x 和 Swagger 2.0 格式并写入 Swagger 2.0。

\n

\n\n

由于您的定义是 Swagger 2.0，我假设您想保留它，因此您需要 Swagger Parser 1.x。

\n\n

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

\n\n

import io.swagger.parser.SwaggerParser;\nimport io.swagger.models.Swagger;\nimport io.swagger.models.Operation;\nimport io.swagger.models.HttpMethod;\nimport io.swagger.models.parameters.QueryParameter;\nimport io.swagger.util.Yaml;\nimport com.fasterxml.jackson.dataformat.yaml.YAMLFactory;\nimport com.fasterxml.jackson.dataformat.yaml.YAMLGenerator;\nimport org.apache.commons.io.FileUtils;\nimport java.io.File;\nimport java.util.Map;\n...\n\nSwagger swagger = new SwaggerParser().read("https://petstore.swagger.io/v2/swagger.json");\n\n// Configure the "status" query parameter\nQueryParameter status = new QueryParameter();\nstatus.setName("status");\nstatus.setType("string");\n// You can also setDescription, setRequired, setExample, etc. as needed\n\n// Get all HTTP methods for the "/pet/{petId}" path\nMap<HttpMethod, Operation> operations = swagger.getPaths().get("/pet/{petId}").getOperationMap();\n\n// Add the "status" parameter to non-GET methods only\nfor (Map.Entry<HttpMethod, Operation> op : operations.entrySet()){\n    if (op.getKey() != HttpMethod.GET) {\n        // TODO: Check if this operation already has\n        // a query parameter named "status"\n\n        op.getValue().addParameter(status);\n    }\n}\n\n// Save the new file\ntry {\n    // (Optional) Configure YAML formatter\n    YAMLFactory factory = (YAMLFactory) Yaml.mapper().getFactory();\n    factory.disable(YAMLGenerator.Feature.WRITE_DOC_START_MARKER)\n        .enable(YAMLGenerator.Feature.MINIMIZE_QUOTES)\n        .enable(YAMLGenerator.Feature.ALWAYS_QUOTE_NUMBERS_AS_STRINGS);\n\n    String yaml = Yaml.pretty().writeValueAsString(swagger);\n    FileUtils.writeStringToFile(new File("C:\\\\Work\\\\petstore-modified.yaml"), yaml);\n}\ncatch (Exception e) {\n    e.printStackTrace();\n}\n

\n\n

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

\n\n

\n

• $ref\'erenced 的路径

  \n\n

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

\n

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

  \n\n

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

\n

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

  \n\n

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

\n

• ETC。

\n

\n