如何将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
相关产品推荐
相关产品推荐

