如何配置Swagger的servers属性实现同域名API版本可选？

在OpenAPI 3.0+规范中，basePath已被servers属性替代，正好适配你的版本切换需求。通过相对路径配置多个server条目，就能实现同域名下的API版本选择，同时默认选中最新的v2版本。

具体YAML配置示例 #

openapi: 3.0.3
info:
  title: 你的API文档标题
  version: 2.0.0
# 核心servers配置
servers:
  - url: /v2
    description: 最新版本API（默认）
    default: true
  - url: /v1
    description: 旧版本API
# 后续是你的API路径定义
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功返回用户列表

配置细节说明 #

• 相对路径url: /v2：由于Swagger UI与API部署在同一域名，使用相对路径会自动继承当前页面的scheme（如https）和host（如their_company_subdomain.myapp.com），完全满足你“复用相同SCHEME和HOST”的要求。
• default: true：标记v2为默认选中版本，打开Swagger页面时会自动使用该basePath发起请求。
• 自动生成下拉框：Swagger UI会将servers数组中的每个条目渲染为下拉选项，用户切换版本后，「Try it out」功能会自动使用对应版本的basePath发送请求。

注意事项 #

• 确保你的OpenAPI版本为3.0及以上，servers属性是3.0版本才引入的，2.0版本不支持该配置。
• API路径定义需基于相对根路径（如/users），不要包含版本前缀，版本前缀已通过servers的url参数统一指定。

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