swagger - 如何在 OpenAPI 2.0 (Swagger 2.0) 中定义自定义 header ？

Question

我在为 OpenAPI (Swagger) 文档定义自定义请求 header 时遇到问题。我查看了文档 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行我收到以下错误:

Schema error at paths['/search'].post.parameters[0].in
should be equal to one of the allowed values
allowedValues: body, header, formData, query, path
Jump to line 37

Schema error at paths['/search'].post.parameters[0]
should NOT have additional properties
additionalProperty: schema, in, name
Jump to line 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