如何使用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: ?

我希望返回不同的格式（csv，json，xml），具体取决于format查询参数的值（例如localhost / api / something？format = csv）。

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

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端点的实际响应头是：

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

我还尝试在yaml中添加标题（在上面的代码之后），但它并没有改变实际的响应标题：

          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被解释为要下载的文件，而不是在浏览器中显示。

...所以我怀疑我还没有完成它。