我在为我的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中,但我不能“保存”它,因为它无效。
答案 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