如何在 OpenAPI (Swagger) 中为同一路径定义不同的主体参数？

Question

我有一个服务，可以根据Content-Type标头有两种不同类型的主体参数。

例如对于路径/Pet：

• 如果Content-Type: application/somecustom.resource+json使用，则POST可以作为Petbody参数。

• 如果Content-Type: application/somecustom.function+json使用，则 POST 应该采用一些不同的主体参数来调用函数并返回不同的响应。

关于如何在 OpenAPI (Swagger) 中体现这一点有什么建议吗？

Answer 1

OpenAPI 3.0 支持每种媒体类型的不同模式。

openapi: 3.0.0
...
paths:
  /pet:
    post:
      requestBody:
        required: true
        content:
          application/somecustom.resource+json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/somecustom.function+json:
            schema:
              $ref: '#/components/schemas/Foo'