Azure API Management如何通过REST API一次性添加同一Schema下多个定义

结论 #

你调用的Azure API Management Schema PUT接口是支持一次性提交多个Schema定义的，你遇到的两个问题均由请求逻辑/请求结构不符合接口规范导致，具体说明和正确调用方式如下：

问题原因说明 #

• 多次调用PUT会覆盖原有内容：该接口为全量替换接口，设计逻辑就是用每次请求提交的内容，直接覆盖对应schemaId下的全部Schema文档，并非增量新增接口，因此无论是否携带If-Match头，多次提交都会保留最后一次的内容。如果需要增量添加定义，需要先调用GET接口拉取当前已有的全量Schema内容，将新定义追加到文档中后再整体PUT提交。
• 提交数组后定义名变成序号：OpenAPI规范中components.schemas节点要求为对象结构，而非数组结构，你提交数组时服务端会自动将数组索引作为每个定义的键名，因此会出现0、1、2这类不符合预期的命名。

正确请求体示例 #

components.schemas直接使用对象结构存储所有定义，不要嵌套数组：

{
  "properties": {
    "contentType": "application/vnd.oai.openapi.components+json",
    "document": {
      "components": {
        "schemas": {
          "Definition1": {
            "type": "object",
            "properties": {
              "String1": {
                "type": "string"
              }
            }
          },
          "Definition2": {
            "type": "object",
            "properties": {
              "String2": {
                "type": "integer"
              }
            }
          }
        }
      }
    }
  }
}

按以上结构提交即可一次性创建多个名称符合预期的Schema定义。

内容的提问来源于stack exchange，提问作者omkar.ghaisas