OpenAPI.yaml配置：实现带空格显示名且锚点链接无%20

核心思路 #

保持name字段为无空格的Team-Game-Stats（保证锚点链接整洁），通过文档渲染工具的自定义配置或选择原生支持x-displayName的工具，让前端显示带空格的Team Game Stats。

1. 针对API标签（Tags） #

原YAML配置无需修改（保留name: Team-Game-Stats和x-displayName: Team Game Stats），如果使用Swagger UI，需要自定义标签渲染逻辑：

const ui = SwaggerUIBundle({
  url: "/openapi.yaml",
  dom_id: '#swagger-ui',
  // 自定义标签显示，优先读取x-displayName
  tagNameRenderer: (tag) => {
    return tag.get('x-displayName') || tag.get('name');
  },
  // 其他默认配置...
});

配置后页面显示Team Game Stats，但锚点链接仍为#/Team-Game-Stats，不会出现%20。

2. 针对组件Schema #

同样保留原YAML中Team-Game-Stats作为schema键名并保留x-displayName配置。若使用Swagger UI，自定义Schema名称渲染逻辑：

const ui = SwaggerUIBundle({
  // 其他配置...
  // 自定义Schema显示名称
  schemaNameRenderer: (schema) => {
    return schema.get('x-displayName') || schema.get('name');
  }
});

3. 零代码替代方案 #

如果不想编写自定义代码，直接更换为Redoc作为文档渲染工具即可。Redoc原生支持x-displayName扩展字段，会自动用该字段显示名称，同时锚点链接沿用无空格的name值，完全满足需求。

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