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

Question

我有一项服务可以根据 Content-Type header 具有两种不同类型的正文参数。

例如对于路径 /Pet:

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

• 如果使用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'