如何配置OpenAPI 3的openapi.yaml实现同一状态码返回CSV/JSON响应？

你的写法确实不符合OpenAPI 3.x的规范，报错原因是响应对象的顶层不允许使用oneOf字段——oneOf是Schema对象的逻辑组合关键字，只能用于定义数据结构的可选性，不能直接用来包裹整个响应的content块。

正确的实现方式 #

OpenAPI 3.x原生支持同一响应返回多种媒体类型，你只需要在200响应的content下直接定义application/json和text/csv两种类型即可，再通过请求头协商让客户端指定格式。

示例配置 #

responses:
  "200":
    description: 报表下载成功
    content:
      application/json:
        schema:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/ReportResponse"
      text/csv:
        schema:
          type: string  # CSV为文本格式，用string类型描述
        example: |
          报表ID,名称,数值
          1,销售报表,15000
          2,库存报表,300

关联请求约束 #

为了明确客户端可以指定的格式，你可以在API的parameters里添加Accept请求头的校验：

parameters:
  - in: header
    name: Accept
    required: true
    schema:
      type: string
      enum:
        - application/json
        - text/csv
    description: 选择响应的媒体类型，支持JSON或CSV格式

关于你提到的oneOf用法 #

你见过的oneOf示例是用于单一媒体类型下的多Schema场景，比如同一个JSON响应可能返回两种不同结构，这种用法是合法的：

application/json:
  schema:
    oneOf:
      - $ref: "#/components/schemas/SuccessResponse"
      - $ref: "#/components/schemas/PartialSuccessResponse"

这种场景下oneOf属于Schema的一部分，而非响应对象的顶层属性，所以不会触发校验错误。

内容的提问来源于stack exchange，提问作者Sukanya Pai