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

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");