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

Question

我有一堆 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 响应内容的正确方法是什么？

Answer 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 规范存储库中寻求说明。

Answer 2

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

OpenAPI yaml.spec：

    get:
      responses:
        200:
          description: Success. It returns CSV format.
          content:
            text/csv:
              schema:
                type: string

后端：

HttpHeaders httpHeaders = new HttpHeaders();
httpHeaders.setContentType(MediaType.parseMediaType("text/csv"));
httpHeaders.setContentDispositionFormData("attachment", "sample.csv");

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