如何在OpenAPI 2.0(Swagger 2.0)中定义自定义标头?

时间:2019-04-18 06:34:37

标签: swagger swagger-2.0 swagger-editor

我在为我的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:正文,标题,formData,查询,路径
  跳到第37行

     

路径['/search'].post.parameters[0]上的架构错误
  不应具有其他属性
  AdditionalProperty:架构,名称,
  跳到第37行

我在这里想念什么?标头显示在渲染的Swagger UI中,但我不能“保存”它,因为它无效。

1 个答案:

答案 0 :(得分:0)

您链接到的指南适用于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