ASP.NET Core中使用Redoc自定义index.html及新增文档页面的技术咨询

场景说明 #

我正在使用ASP.NET Core搭配Swagger，并采用Redoc作为API文档工具，相关配置代码如下：

app.UseReDoc(c =>
{
    c.DocumentTitle = "API Documentation";
    c.SpecUrl = "/swagger.json";
});

当前api-docs的默认路由为/api-docs/index.html。我有两个技术问题需要咨询：

1. 是否可以自定义index.html页面？
2. 是否能够为文档添加另一个自定义页面？

问题1：是否可以自定义index.html页面？ #

可以实现。Redoc中间件支持替换默认的index.html页面，具体操作如下：

• 先准备自定义HTML页面：可以参考Redoc默认模板的结构，确保页面中引入Redoc核心脚本，并正确配置Swagger JSON的访问路径
• 放置自定义页面：
  • 若作为嵌入式资源：将页面添加到项目后，设置其“生成操作”为“嵌入式资源”
  • 若作为静态文件：直接放在项目的wwwroot目录下，确保已配置静态文件中间件
• 修改Redoc配置指向自定义页面：

app.UseReDoc(c =>
{
    c.DocumentTitle = "API Documentation";
    c.SpecUrl = "/swagger.json";
    // 嵌入式资源方式示例，替换为你的项目命名空间和资源路径
    c.IndexStream = () => typeof(Program).Assembly.GetManifestResourceStream("YourProjectNamespace.wwwroot.redoc-custom.index.html");
});

问题2：是否能够为文档添加另一个自定义页面？ #

可以，有两种实用方案：

• 方案一：添加独立静态页面
  在项目wwwroot目录下创建自定义页面（比如api-guides.html），ASP.NET Core静态文件中间件默认允许直接通过路由（如/api-guides.html）访问。页面内容可完全自定义，比如编写API使用教程、常见问题等。
• 方案二：与Redoc文档整合
  若想让自定义页面和Redoc API文档关联，可在自定义的Redoc index.html中添加额外导航元素（比如侧边栏链接）指向自定义页面；或者在Redoc页面模板中嵌入自定义内容区块，实现文档一体化展示。

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