OpenAPI 3.0 파라미터 content의 복수 항목

설명

OpenAPI 3.0의 Parameter 객체에서 content는 정확히 하나의 미디어 타입 항목을 가져야 합니다. application/json과 application/xml을 함께 넣는 등 여러 항목을 지정하면 Parameter 객체의 형식에 맞지 않습니다.

잠재적 영향

검증 도구가 문서를 거부하거나 클라이언트 생성에 문제가 생길 수 있습니다.
API 사용자가 파라미터 값을 어떤 형식으로 보내야 하는지 혼동할 수 있습니다.

해결 방법

파라미터의 content에 실제로 사용할 미디어 타입 하나만 남기고 해당 형식의 스키마와 예시를 확인하세요. 같은 Parameter 객체에 schema와 content를 함께 지정하지 마세요. 여러 요청 본문 형식을 지원하려는 목적이라면 요청 본문 계약을 별도로 설계하세요.

예시

작업과 경로 수준의 파라미터에서 두 미디어 타입을 지정한 경우와 하나만 지정한 경우를 비교합니다. 참조하는 User 스키마와 외부 예시 파일은 별도로 준비해야 합니다.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/user/{id}": {
      "parameters": [
        {
          "description": "ID of the API version",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/User"
              },
              "examples": {
                "user": {
                  "summary": "User Example",
                  "externalValue": "http://foo.bar/examples/user-example.json"
                }
              }
            },
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/User"
              },
              "examples": {
                "user": {
                  "summary": "User Example in XML",
                  "externalValue": "http://foo.bar/examples/user-example.xml"
                }
              }
            }
          },
          "name": "id",
          "in": "path"
        }
      ]
    },
    "/{id}": {
      "get": {
        "summary": "List API versions",
        "parameters": [
          {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                },
                "examples": {
                  "user": {
                    "summary": "User Example",
                    "externalValue": "http://foo.bar/examples/user-example.json"
                  }
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                },
                "examples": {
                  "user": {
                    "summary": "User Example in XML",
                    "externalValue": "http://foo.bar/examples/user-example.xml"
                  }
                }
              }
            },
            "name": "id",
            "in": "path",
            "description": "ID of the API version",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "foo": {
                    "value": {
                      "versions": [
                        {
                          "updated": "2011-01-21T11:33:21Z",
                          "id": "v2.0",
                          "links": [
                            {
                              "rel": "self",
                              "href": "http://127.0.0.1:8774/v2/"
                            }
                          ],
                          "status": "CURRENT"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "description": "200 response"
          }
        },
        "operationId": "listVersionsv2"
      }
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/user/{id}": {
      "parameters": [
        {
          "description": "ID of the API version",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/User"
              },
              "examples": {
                "user": {
                  "summary": "User Example",
                  "externalValue": "http://foo.bar/examples/user-example.json"
                }
              }
            }
          },
          "name": "id",
          "in": "path"
        }
      ]
    },
    "/{id}": {
      "get": {
        "summary": "List API versions",
        "parameters": [
          {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                },
                "examples": {
                  "user": {
                    "summary": "User Example",
                    "externalValue": "http://foo.bar/examples/user-example.json"
                  }
                }
              }
            },
            "name": "id",
            "in": "path",
            "description": "ID of the API version",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "foo": {
                    "value": {
                      "versions": [
                        {
                          "updated": "2011-01-21T11:33:21Z",
                          "id": "v2.0",
                          "links": [
                            {
                              "rel": "self",
                              "href": "http://127.0.0.1:8774/v2/"
                            }
                          ],
                          "status": "CURRENT"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "description": "200 response"
          }
        },
        "operationId": "listVersionsv2"
      }
    }
  }
}

변경 후에는 각 content에 application/json만 남깁니다. 경로의 id와 파라미터 이름을 일치시키고, content와 함께 둘 수 없는 별도의 schema 필드는 제거했습니다.