format - 如何使用swagger/OpenAPI指定替代响应格式？

Question

我有一个 swagger.yaml 像这样的东西:

swagger: "2.0"
paths:
  /something:
    get:
      parameters:
        - name: format
          in: query
          type: string
          pattern: '^(csv|json|xml)$'
      responses:
        200:
          schema:
            type: ?

我想根据 format查询参数的值(例如localhost/api/something？format = csv)返回不同的格式(csv，json，xml)。

如何在规范中指定不同的响应格式？

Answer 1

通过提供不同的端点，我找到了一种解决方法:

swagger: "2.0"
paths:
  /something/json:
    get:
      produces:
        - application/json
      responses:
        200:
          schema:
            type: object
            properties:
              ...
  /something/csv:
    get:
      produces:
        - text/csv
      responses:
        200:
          schema:
            type: string          

注意每个 produces:内的不同 get，但在顶层没有一个。

csv端点的实际响应 header 是:

Content-Length:64
Content-Type:text/csv; charset=utf-8
Date:Fri, 26 Aug 2016

我也尝试将 header 添加到yaml中(紧接在上面的代码之后)，但是它不会更改实际的响应 header :

          headers:
            Content-type:
              type: string
              description: text/csv; charset=utf-8
            Content-Disposition:
              type: string
              description: attachment; filename=data.csv

在任一端点上，我都会收到一条控制台消息(我正在使用 connexion构建此消息):
Resource interpreted as Document but transferred with MIME type application/json，或
Resource interpreted as Document but transferred with MIME type text/csv
此外，csv会被解释为要下载的文件，而不显示在浏览器中。

...所以我怀疑我还没有完全正确。