How to properly document text/csv responses on swagger/yaml docs?

Question

I have a bunch of API endpoints that return text/csv content in their responses. How do I document this? Here is what I currently have:

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

As it stands, this does not work and I get the note in the Swagger preview:

Could not render this component, see the console.

The question is how do I properly display the content for csv responses? I find if does work if I do add a schema, something like this:

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

But there shouldn't be a schema since it is csv. So to go back to the question, what is the proper way to describe the csv response content?

Answer 1

Your first example is not valid syntax. Replace with:

      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

As for your second example, OpenAPI Specification does not provide examples of CSV responses. So the schema could be type: string, or an array of strings, or an empty schema {} (this means "any value"), or something else. The actual supported syntax might be tool-dependent. Feel free to ask for clarifications in the OpenAPI Specification repository.

Answer 2

Here is another worked one for openapi 3.0.2 to return text/csv content (string) from backend:

Contract:

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

Backend:

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

Answer 3

Here is one more example:

Contract:

  responses:
    '200':
      schema:
        type: object

Backend:

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