是否可以在 OpenAPI 2.0 规范中为所有路径添加前缀？

Question

我有一个 API 的 Swagger 规范，如下所示：

swagger: '2.0'
info:
  title: my-api
  description: My API
  version: v1
schemes:
  - https
produces:
  - application/json
paths:
  /v1/entry/check:
    post:
      ...
  /v1/entry/enter:
    post:
      ...
  /v1/exit/leave:
    post:
      ...
...

正如您所看到的，中的每个路径都paths带有前缀/v1/，因为规范描述了v1API 的版本（您也可以在info.version值中看到）。

我想知道，有没有办法避免重复这个前缀，即隐式地为所有路径添加前缀/v1/？主要是，我想这样做是为了避免任何意外滥用规范，即完全防止添加另一个没有前缀的路径。

Answer 1

在 OpenAPI 2.0 中，您可以将前缀指定为basePath：

basePath: /v1
paths:
  /entry/check:
    ...
  /entry/enter
    ...

在 OpenAPI 3.x 中，前缀是由以下方式指定的 API 服务器 URL 的一部分servers[].url：

servers:
  - url: /v1  # or https://my.api.com/subpath/v1 if you need an absolute URL
paths:
  /entry/check:
    ...
  /entry/enter
    ...