我在为 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 37Schema error at paths['/search'].post.parameters[0]
should NOT have additional properties
additionalProperty: schema, in, name
Jump to line 37
我在这里缺少什么?标题显示在渲染的 Swagger UI 中,但我无法“保存”它,因为它无效。
最佳答案
您链接到的指南适用于 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
关于swagger - 如何在 OpenAPI 2.0 (Swagger 2.0) 中定义自定义 header ?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/55740331/