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

Question

我有一个这样的网址:

/id/{idnumber}/status

在此 URL 中， /id/{idnumber}是 API 基本路径， /status是资源。

我知道 OpenAPI (Swagger) 允许路径中的参数，如下所示:

paths:
  /id/{number}/status:

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

有没有办法在基本路径中有一个参数？

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

paths:
  /status:

Answer 1

OpenAPI 3.0 现在支持参数化基本路径，使用服务器变量:

openapi: 3.0.0
...

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

请注意，服务器变量必须有 default value - 如果客户端不提供值，它将被使用。

有关详细信息，请参阅:

Server Object和 Server Variable Object OpenAPI 3.0 规范的部分

API Server and Base URL在 swagger.io