向 OpenAPI 3.0.x 中的现有响应架构添加新属性

Question

我有四个路径 a、b、c、d。所有路径之前都具有相同的属性和模式。现在有一个新的要求，其中路径 c 和 d 将在名为 rex 的属性中发生更改。定位在这里很重要，我该如何实现这个。

我们可以看到，响应 200 ref 对于所有四个路径都是相同的，但对于名为 rex 的某些属性的路径 c 和 d，我需要覆盖其定义的现有方式。

{
  "paths": {
    "/example/version/path-a": {
      "get": {
        "summary": "Get Details by path a",
        "tags": [
          "GET"
        ],
        "operationId": "",
        "description": "",
        "parameters": [
          {
            "$ref": "#/components/parameters/path-a"
          },
          {
            "$ref": "#/components/parameters/auth"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/200-get"
          },
          "400": {
            "$ref": "#/components/responses/400-get"
          },
          "404": {
            "$ref": "#/components/responses/404-get"
          },
          "500": {
            "$ref": "#/components/responses/500-get"
          }
        }
      }
    },
    "/example/version/path-b": {
      "get": {
        "summary": "Get Details by path-b",
        "tags": [
          "GET"
        ],
        "operationId": "",
        "description": "",
        "parameters": [
          {
            "$ref": "#/components/parameters/auth"
          },
          {
            "$ref": "#/components/parameters/path-b"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/200-get"
          },
          "400": {
            "$ref": "#/components/responses/400-get"
          },
          "404": {
            "$ref": "#/components/responses/404-get"
          },
          "500": {
            "$ref": "#/components/responses/500-get"
          }
        },
        "security": [
          {
            "forge-token": []
          }
        ]
      }
    },
    "/example/version/path-c/": {
      "get": {
        "summary": "Get by path c",
        "tags": [
          "GET"
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/200-get"
          },
          "400": {
            "$ref": "#/components/responses/400-get"
          },
          "404": {
            "$ref": "#/components/responses/404-get"
          },
          "500": {
            "$ref": "#/components/responses/500-get"
          }
        },
        "operationId": "",
        "parameters": [
          {
            "$ref": "#/components/parameters/path-c"
          },
          {
            "$ref": "#/components/parameters/auth"
          }
        ],
        "description": ""
      }
    },
    "exmple/version/path-d": {
      "get": {
        "summary": "Get details by d",
        "tags": [
          "GET"
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/200-get"
          },
          "400": {
            "$ref": "#/components/responses/400-get"
          },
          "404": {
            "$ref": "#/components/responses/404-get"
          },
          "500": {
            "$ref": "#/components/responses/500-get"
          }
        },
        "operationId": "",
        "parameters": [
          {
            "$ref": "#/components/parameters/path-d"
          },
          {
            "$ref": "#/components/parameters/auth"
          }
        ],
        "description": ""
      }
    }
  }
}

Answer 1

定义新的响应模式并使用

allOf

引用它

{
  "components": {
    "responses": {
      "200": {
        "description": "OK",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/original_schema"
            }
          }
        }
      },
      "200-updated": {
        "description": "this response has the new property and the old property",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/original_schema"
                },
                {
                  "$ref": "#/components/schemas/new_schema"
                }
              ]
            }
          }
        }
      }
    },
    "schemas": {
      "original_schema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          }
        }
      },
      "new_schema": {
        "type": "object",
        "properties": {
          "age": {
            "type": "number"
          }
        }
      }
    }
  }
}