Openapi3 and CSV response (for Dredd)

Question

I test my Api with DREDD against it's specification (written in Openapi3 considering, painfull limitations of Support by Dredd considered). No I have one endpoint, which produces CSV-data if the Accept-header is set so.

    '/my-endpoint':
        summary: ...
        description: ...
        get:
 #          parameters:
 #              - 
 #                  in: header
 #                  name: Accept
 #                  description: "Response format: application/json or text/csv"
 #                  example: "text/csv"
            responses:
                '200':
                    description: ...
                    content:
                        text/csv:
                            schema:
                                type: string
                            example:
                                summary: 'csv table'
                                value: 'cell1, cell2'

When I run the test with Dredd the test fails with


expected: 
headers: 

body: 
[
  {
    "key": "summary",
    "value": "csv table"
  },
  {
    "key": "value",
    "value": "cell1, cell2"
  }
]
statusCode: 200

Clearly there is something misunderstood and Dredd expects still JSON. Also the API is not told to produce the CSV Version. If I commit in the Accept header in the code abvoe I get the very same result - the expecetd result above and as actual result the JSON version of the my-endpoint-data and also ad warning:

warn: API description parser warning in .../tmp/transformed.specs.yml: 'Parameter Object' 'name' in location 'header' should not be 'Accept', 'Content-Type' or 'Authorization'

I read here and here: Header parameters named Accept, Content-Type and Authorization are not allowed. To describe these headers, use the corresponding OpenAPI keywords - but what are they? According to this and this page it seems to be enough to specify a response of the given type but that is clearly not enough to tell Dredd to produce such a header.

Regarding the Accept parameter, check the clause in the OpenAPI 3 specification at https://spec.openapis.org/oas/v3.0.2#fixed-fields-9. In particular: "If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored.". Thus it isn't possible to declare an Accept header in this way. — kylef, Feb 17 '20 at 14:33
The `Accept` header is inferred from `responses..content.` values. — Helen, Feb 17 '20 at 14:39
This is a bug in the parser used by Dredd, I've created https://github.com/apiaryio/api-elements.js/issues/413 to track the fix. — kylef, Feb 17 '20 at 14:46
Thanks! It's quite a relief to know I understood things correctly and the problem is somewhere else... — Paflow, Feb 17 '20 at 16:07

score 5 · Accepted Answer · answered Feb 17 '20 at 14:43

You got an error because the value of the example key is meant to be a literal example value. So in your case it's treated as an object with the summary and value properties.

Change your definition to:

                    content:
                        text/csv:
                            schema:
                                type: string
                            example: 'cell1, cell2'

Or if you want to provide a summary/description for an example, use examples instead:

                    content:
                        text/csv:
                            schema:
                                type: string
                            examples:
                                csv table:
                                    summary: A CSV table with 2 cells
                                    value: 'cell1, cell2'

Openapi3 and CSV response (for Dredd)

1 Answers1