You need to enable JavaScript to run this app. 如何将README文件添加到集成Swagger的Redoc文档侧边栏
优惠活动
大模型
产品
解决方案
定价
更多

如何将README文件添加到集成Swagger的Redoc文档侧边栏

自有README内容接入Redoc左侧侧边栏实现方案

Redoc的侧边栏自定义内容没有独立的外部文件加载入口,所有非接口类的侧边栏节点,全部来源于OpenAPI规范(即你生成的swagger.json)根节点下info.description字段中的Markdown内容——它会自动识别该字段内的标准Markdown标题,按层级生成可跳转的侧边栏节点,天然支持深度链接能力,这也是官方内置的内容集成机制。

具体实现步骤

  • 找到项目中注册Swagger服务、配置swagger.json生成规则的代码段(注意是依赖注入部分的Swagger配置,不是后续调用app.UseReDoc的中间件配置部分)
  • 在配置Swagger文档元信息的OpenApiInfo对象中,找到Description属性,将自有README的全部Markdown内容赋值给该属性
  • 若不想把README内容硬编码在代码中,可将项目内的README.md文件设置为复制到输出目录,程序启动时通过文件读取的方式获取README内容,再赋值给Description属性,避免内容维护时需要反复修改C#代码
  • 原有app.UseReDoc的中间件配置完全不需要大改,补全代码里遗漏的SpecUrl字段开头的双引号即可,调整后的配置如下,不需要额外新增参数:
app.UseReDoc(c =>
{
    c.DocumentTitle = $"Documentation";
    c.SpecUrl = "/api/docs/swagger.json";
    c.RoutePrefix = "docs";
});

常见踩坑说明

  • 不存在所谓“直接传入README文件路径”的Redoc内置配置项,不要在ReDoc中间件配置段找相关参数,所有自定义介绍内容的唯一入口就是OpenAPI的description字段
  • 侧边栏节点的生成依赖规范的Markdown标题语法(即#、##、###层级的标题),普通文本、加粗内容不会被识别为侧边栏节点
  • 嵌入description字段的Markdown内容完全兼容常规语法,代码块、列表、图片、行内格式都能正常渲染,不需要做额外的格式转换

内容的提问来源于stack exchange,提问作者andrey1567

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.29 22:54:08