如何在OpenAPI 2.0（Swagger 2.0）中定义自定义标头？

Question

我在为OpenAPI（Swagger）文档定义自定义请求标头时遇到问题。我查看了文档https://swagger.io/docs/specification/describing-parameters/#header-parameters，但我无法让它工作。

在我的示例中，下面是一个POST请求，它有一个正文。我也希望它有一个自定义标题，就像我的第二个片段，但这是无效的。

还行吧：

 /search:
    post:
      tags:
        - Domain
      summary: Search for domains
      description: Returns a domain if it was found.
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: Array of Domain Names
          required: true
          schema:
            $ref: '#/definitions/DomainNames'

这不行：

  /search:
    post:
      tags:
        - Domain
      summary: Search for domains
      description: Returns a domain if it was found.
      produces:
        - application/json
      parameters:
       - in: header
          name: X-Request-ID
          schema:
            type: string
            format: uuid
          required: true
        - in: body
          name: body
          description: Array of Domain Names
          required: true
          schema:
            $ref: '#/definitions/DomainNames'

在- in: header线上，我收到以下错误：

路径['/ search']上的模式错误.post.parameters [0] .in 应该等于允许值之一 allowedValues：body，header，formData，query，path 跳到第37行

路径['/ search']上的模式错误.post.parameters [0] 不应该有其他属性 additionalProperty：schema，in，name 跳到第37行

我在这里错过了什么？标题显示在渲染的Swagger UI中，但我无法“保存”它，因为它无效。

Answer 1

您链接的指南适用于OpenAPI 3.0（如该页面顶部所示）。相应的OpenAPI 2.0指南在这里：Describing Parameters。

在OpenAPI 2.0中，path / header / query / form参数不使用schema，它们直接使用type关键字。

此外，示例中的- in: header行没有足够的缩进，您需要在它之前再添加一个空格以使其与其他行对齐。

这是正确的版本：

      parameters:
        - in: header     # <----
          name: X-Request-ID
          type: string   # <----
          format: uuid   # <----
          required: true