在OpenAPI中，能否将info.version作为路径参数的默认值？

我正在编写OpenAPI格式的API规范，希望通过请求头中的版本参数让代码识别调用的版本，方便未来版本变更。我想把info.version的值作为X-Version请求头参数的默认值，示例代码如下：

openapi: 3.0.3
info:
  title: JXG API
  version: 1.2.3

servers:
  - url: https://jxg.info/api

paths:
  /jxg:
    get:
      parameters:
        - in: header
          name: X-Version
          schema:
            type: string
            default: <info.version>
      responses:
        "200":
          description: OK.

请问是否有办法实现上述需求？我查阅了官方文档，但未找到相关说明。

解决方案 #

OpenAPI 3.x规范本身不支持直接引用info.version作为参数的default值，因为OpenAPI的Schema Object没有提供这种跨字段引用的语法。不过可以通过以下方式实现类似需求：

1. 手动同步版本值 #

直接将default字段设置为和info.version完全相同的字符串，比如：

parameters:
  - in: header
    name: X-Version
    schema:
      type: string
      default: "1.2.3"

每次更新API版本时，同时修改info.version和这个default值即可。这种方式简单直接，适合小型API或版本更新不频繁的场景。

2. 使用工具自动同步 #

如果API文档规模较大、版本更新频繁，可以借助工具实现自动同步：

• 编写自定义脚本（比如Node.js或Python脚本），读取OpenAPI文件中的info.version值，自动替换参数default字段的内容；
• 使用openapi-generator等工具，通过自定义模板在生成代码或文档时完成变量替换；
• 利用swagger-cli这类工具结合JSON Schema的引用能力，通过额外配置实现字段值的复用。

替代方案：路径中包含版本号 #

如果你的核心需求是让客户端明确识别调用的API版本，更推荐将版本号放在路径中（比如/v1/jxg），这种方式是RESTful API的常见实践，OpenAPI天然支持路径版本号的定义，无需处理请求头默认值的同步问题。

内容的提问来源于stack exchange，提问作者JXG