You need to enable JavaScript to run this app. OpenAPI Specification V3中如何正确定义Accept请求头
优惠活动
大模型
产品
解决方案
定价
更多

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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.17 03:24:03