如何在Redocly文档中移除路径别名以避免重复内容展示？

嗨，我完全懂你的困扰——为了兼容旧版API保留了路径别名，但Redocly文档里重复展示这些内容，确实会让看文档的开发者感到混乱。别担心，这里有几个实用的解决办法，而且完全不会影响后端的向后兼容：

方法一：通过Redocly配置直接排除指定路径 #

Redocly支持在配置文件里指定要隐藏的路径，生成文档时就不会展示这些别名了。操作很简单：

1. 找到项目根目录的redocly.yaml（没有的话就新建一个）
2. 添加excludePaths配置，把需要隐藏的别名路径列进去：

theme:
  openapi:
    excludePaths:
      - /municipio/{municipio}
      # 要是还有其他别名路径，继续在这里追加即可

配置完成后，Redocly生成的文档只会展示原路径/municipios/{municipio}，别名路径会被隐藏，但原始OpenAPI文件里的别名依然保留，完全不影响后端服务的兼容性。

方法二：预处理OpenAPI文件（自动清理别名） #

如果你的别名路径比较多，不想手动一个个列出来，可以写个简单脚本，在生成文档前临时清理掉这些别名，而且不会修改原始文件：

1. 先安装js-yaml依赖（用来解析YAML文件）：

npm install js-yaml --save-dev

2. 创建清理脚本，比如命名为clean-openapi.js：

const fs = require('fs');
const yaml = require('js-yaml');

// 加载原始的OpenAPI文件
const openapi = yaml.load(fs.readFileSync('openapi.yaml', 'utf8'));

// 自动识别并移除所有带$ref的路径别名
Object.keys(openapi.paths).forEach(path => {
  const pathDef = openapi.paths[path];
  if (pathDef.$ref) {
    delete openapi.paths[path];
  }
});

// 将清理后的内容保存为临时文件
fs.writeFileSync('openapi-clean.yaml', yaml.dump(openapi));

3. 运行脚本+生成文档：

node clean-openapi.js && redocly build-docs openapi-clean.yaml -o api-docs.html

这种方法能自动过滤所有路径别名，适合别名数量较多的场景。

方法三：自定义Redocly插件（灵活定制规则） #

如果需要更复杂的过滤逻辑（比如根据特定关键词判断别名），可以写个Redocly插件来处理：

1. 创建插件文件，比如remove-path-aliases.js：

module.exports = {
  id: 'remove-path-aliases',
  hooks: {
    // 在文档渲染前修改OpenAPI内容
    preRender: (openapi) => {
      // 遍历所有路径，移除带$ref的别名路径
      Object.keys(openapi.paths).forEach(path => {
        if (openapi.paths[path].$ref) {
          delete openapi.paths[path];
        }
      });
      return openapi;
    }
  }
};

2. 在redocly.yaml里配置使用这个插件：

plugins:
  - ./remove-path-aliases.js

之后正常生成文档就行，插件会自动在渲染前清理掉所有路径别名。

以上三种方法都不会改动你的原始openapi.yaml文件，后端服务的向后兼容完全不受影响，只是在文档里隐藏了这些重复的别名路径。

备注：内容来源于stack exchange，提问作者João Pimentel Ferreira