如何使用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查询参数的值返回不同的格式(csv,json,xml)(例如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被解释为要下载的文件,而不是在浏览器中显示.

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