Openapi3 和 CSV 响应（用于 Dredd）答案

【问题标题】：Openapi3 and CSV response (for Dredd)Openapi3 和 CSV 响应（用于 Dredd）
【发布时间】：2020-02-17 14:15:49
【问题描述】：

我使用 DREDD 对照它的规范测试我的 Api（考虑到，用 Openapi3 编写，painfull limitations of Support by Dredd considered）。不，我有一个端点，如果设置了 Accept-header，它会生成 CSV 数据。

    '/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'

当我使用 Dredd 运行测试时，测试失败


expected: 
headers: 

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

显然有些地方被误解了，Dredd 期望仍然是 JSON。此外，API 没有被告知生成 CSV 版本。如果我在代码 abvoe 中的 Accept 标头中提交，我会得到完全相同的结果 - 上面的预期结果和实际结果是 my-endpoint-data 的 JSON 版本以及广告警告：

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

我读过here 和here：Header parameters named Accept, Content-Type and Authorization are not allowed. To describe these headers, use the corresponding OpenAPI keywords - 但它们是什么？根据 this 和 this 页面，指定给定类型的响应似乎就足够了，但这显然不足以告诉 Dredd 生成这样的标头。

【问题讨论】：

关于 Accept 参数，请查看 OpenAPI 3 规范中spec.openapis.org/oas/v3.0.2#fixed-fields-9 中的子句。特别是：“如果 in 是“header”并且名称字段是“Accept”、“Content-Type”或“Authorization”，则应忽略参数定义。”。因此不可能以这种方式声明 Accept 标头。
Accept 标头是从 responses.<code>.content.<media-type> 值推断出来的。
这是 Dredd 使用的解析器中的一个错误，我创建了 github.com/apiaryio/api-elements.js/issues/413 来跟踪修复。
谢谢！知道我正确理解了事情并且问题出在其他地方，这真是一种解脱......

标签： openapi dredd

【解决方案1】：

您收到错误，因为 example 键的值是一个文字示例值。因此，在您的情况下，它被视为具有 summary 和 value 属性的对象。

将您的定义更改为：

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

或者，如果您想为示例提供摘要/描述，请改用 examples：

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

【讨论】：