OpenAPI Specification V3中如何正确定义Accept请求头
OpenAPI V3 定义Accept请求头的正确方式
原写法问题说明
OAS3 规范明确将Accept、Content-Type这类标准HTTP头列为隐式参数,不建议手动在parameters的header节点下重复定义。Azure APIM这类合规的OAS解析工具会优先读取规范内的标准声明,自动忽略手动重复定义的Accept头,这就是你遇到的导出后参数不显示的原因,SwaggerUI因为兼容非规范写法所以可以正常展示。
正确实现方式
你不需要手动在parameters里定义Accept头,只需要将需要支持的媒体类型声明在对应接口响应的content节点下即可,OAS会自动基于这些声明生成对应的Accept头选项,示例如下:
paths: /device-enrollment: # 替换为你的实际接口路径 get: # 替换为你的实际请求方法 summary: 设备注册接口 responses: '200': description: 请求处理成功 content: # 按顺序声明你支持的媒体类型,对应原来的enum取值 application/vnd.iotdeviceenrollment.v1: schema: # 此处填写v1版本响应对应的结构体定义 type: object properties: deviceId: type: string status: type: string application/json: schema: # 此处填写通用json格式响应对应的结构体定义 type: object properties: code: type: integer message: type: string
额外说明
如果你是基于Accept头实现API版本控制,需要明确告知调用方必须传入指定格式的Accept头,可以在接口的description字段中补充说明规则,不需要额外手动定义头参数。
这种写法完全符合OAS3官方规范,SwaggerUI、Azure APIM、Postman等所有支持OAS的工具都可以正常识别,自动生成Accept头的可选值列表,不会出现被忽略的问题。
内容的提问来源于stack exchange,提问作者Harshith R
相关产品推荐
相关产品推荐

