如何在 OpenAPI (Swagger) 中参数化 API 基本路径？

我有一个像这样的网址：

/id/{idnumber}/status

在这个网址中，/id/{idnumber}是 API 基本路径，并且/status是资源。

我知道 OpenAPI (Swagger) 允许在路径中使用参数，如下所示：

paths:
  /id/{number}/status:

但这不是我需要的，因为/id/{idnumber}是基本路径，而不是资源路径的一部分。

有什么办法可以在基本路径中包含参数吗？

host: my.api.com
basePath: /id/{idnumber}   # <---

paths:
  /status:

OpenAPI 3.x 支持参数化基本路径，使用服务器变量:

openapi: 3.0.0
...

servers:
  - url: https://my.api.com/id/{number}
    variables:
      number:
        default: '-1'

请注意，服务器变量必须有一个defaultvalue - 如果客户端未提供值，则将使用该值。

详细信息请参见：

• 服务器对象 https://spec.openapis.org/oas/v3.1.0.html#server-object and 服务器变量对象 https://spec.openapis.org/oas/v3.1.0.html#server-variable-objectOpenAPI 3.0 规范的各个部分
• API 服务器和基本 URL https://swagger.io/docs/specification/api-host-and-base-path/在 swagger.io 上