如何在 swagger/yaml 文档上正确记录文本/csv 响应？

Posted 2023-03-15

【中文标题】如何在 swagger/yaml 文档上正确记录文本/csv 响应？

【英文标题】：How to properly document text/csv responses on swagger/yaml docs?

【发布时间】：2020-04-30 12:35:06

【问题描述】：

我有一堆 API 端点在它们的响应中返回 text/csv 内容。我该如何记录？这是我目前拥有的：

  /my_endpoint:
    get:
      description: Returns CSV content
      parameters:
        - $ref: '#/components/parameters/myParemeters'
      responses:
        200:
          headers:
            $ref: '#/components/headers/myHeaders'
          content: text/csv

就目前而言，这不起作用，我在 Swagger 预览中得到了注释：

无法渲染此组件，请查看控制台。

问题是如何正确显示 csv 响应的内容？我发现如果我确实添加了一个模式，是否可以工作，如下所示：

...
  content:
      text/csv:
        schema:
          type: array
          items:
            type: string
...

但不应该有模式，因为它是 csv。那么回到这个问题，描述 csv 响应内容的正确方法是什么？

【参考方案1】：

您的第一个示例语法无效。替换为：

      responses:
        '200':
          content:
            text/csv:   # <-----

          # Also note the correct syntax for referencing response headers:
          headers:
            Http-Header-Name:  # e.g. X-RateLimit-Remaining
              $ref: '#/components/headers/myHeader'

components:
  headers:
    myHeader:
      description: Description of this response header
      schema:
        type: string

至于您的第二个示例，OpenAPI 规范不提供 CSV 响应示例。所以schema 可以是type: string，或者一个字符串数组，或者一个空模式（这意味着“任何值”），或者其他的东西。实际支持的语法可能取决于工具。请随时在OpenAPI Specification repository 中寻求澄清。

【参考方案2】：

这是 openapi 3.0.2 从后端返回文本/csv 内容（字符串）的另一个工作：

合同：

        responses:
            '200':
                content:
                    text/csv:
                        schema:
                            type: string
                            
                            

后端：

return ResponseEntity.ok("h1,h2,h3,h4\n1,2,3,4\n5,6,7,8");

【参考方案3】：

这里还有一个例子：

合同：

  responses:
    '200':
      schema:
        type: object

后端：

return ResponseEntity.status(200).contentType(MediaType.parseMediaType("text/csv")).body("Col 1;Col2\naaa;bbb\nccc;ddd");

【讨论】：

您的答案可以通过额外的支持信息得到改进。请edit 添加更多详细信息，例如引用或文档，以便其他人可以确认您的答案是正确的。你可以找到更多关于如何写好答案的信息in the help center。