能否实现OpenAPI的servers列表动态化或按需隐藏？

OpenAPI规范本身没有内置的“部分内容隐藏”机制，没法让同一个文件既保留servers段又让客户看不到。但你可以通过构建流程/工具链实现「一份源文件维护，两份输出」——内部用带servers的版本，给客户的是移除servers的版本。下面是几种实用方案：

方案1：用脚本自动生成客户版定义 #

写个简单的脚本读取原始OpenAPI文件，删除servers字段后输出客户专用版本，每次交付前跑一遍脚本即可。

比如用Python+PyYAML实现的脚本：

import yaml

# 读取源文件
with open('openapi-internal.yaml', 'r', encoding='utf-8') as f:
    spec = yaml.safe_load(f)

# 移除servers字段（如果存在）
spec.pop('servers', None)

# 写入客户版文件
with open('openapi-client.yaml', 'w', encoding='utf-8') as f:
    yaml.dump(spec, f, sort_keys=False, allow_unicode=True)

方案2：用自定义扩展标记，工具过滤内部服务器 #

给内部服务器条目加上自定义扩展（比如x-internal: true），再用OpenAPI工具过滤掉带该标记的条目，既能保留内部服务器，又能灵活区分可对外展示的服务器。

修改后的源文件示例：

openapi: '3.0.2'
info:
  title: Application interfaces
  version: '1.0.0'
  name: Our application
  url: http://x.y.z.com

servers:
  - url: http://localhost:8088
    description: local debug
    x-internal: true
  - url: https://test1.xyz.com/
    description: Test env 1
    x-internal: true
  - url: https://test2.xyz.com/
    description: Test env 2
    x-internal: true
  # 若有需要对外展示的服务器，不加x-internal标记即可
  # - url: https://prod.xyz.com/
  #   description: Production environment

用Redocly的openapi-cli工具过滤的命令：

# 安装工具：npm install -g @redocly/openapi-cli
openapi filter openapi-internal.yaml --out openapi-client.yaml --remove "servers[?x-internal]"

方案3：文件拆分+合并 #

把servers段单独放在一个内部专用文件里，公共部分放在主文件中。内部使用时用工具合并两个文件，给客户的直接用主文件。

比如：

• openapi-base.yaml：不含servers字段的公共定义
• openapi-servers-internal.yaml：仅包含内部servers的片段

用swagger-cli合并生成内部版：

# 安装工具：npm install -g swagger-cli
swagger-cli bundle openapi-base.yaml -o openapi-internal.yaml --extend openapi-servers-internal.yaml

交付客户时直接提供openapi-base.yaml即可。

内容的提问来源于stack exchange，提问作者Marc Le Bihan