如何在ASP.NET Core 6的Redoc API文档中添加自定义文本模块

要实现类似目标网站的自定义文本模块，核心是通过修改OpenAPI文档结构，让Redoc能识别并渲染这些自定义内容。以下是针对Redoc适配的可行方案：

方案1：通过文档过滤器扩展OpenAPI的Info描述 #

Redoc会渲染OpenAPI文档中info.description字段的Markdown内容，你可以通过Swashbuckle的文档过滤器添加多段自定义文本：

1. 创建自定义文档过滤器类

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public class CustomTextDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // 添加Markdown格式的自定义文本，支持标题、段落、列表等
        swaggerDoc.Info.Description = @"
# 介绍
这是自定义的API文档介绍模块，支持Markdown语法。

## 快速开始
- 首先获取API密钥
- 调用认证接口获取Token
- 开始调用业务接口

## 注意事项
所有接口请求需携带`Authorization: Bearer {Token}`头
";
    }
}

2. 在Program.cs中注册过滤器

builder.Services.AddSwaggerGen(c =>
{
    // 其他Swagger配置...
    c.DocumentFilter<CustomTextDocumentFilter>();
});

方案2：添加自定义标签组与分组描述 #

如果需要给不同API分组添加自定义文本，可以通过x-tagGroups扩展字段实现，Redoc会识别该字段并渲染分组说明：

1. 修改文档过滤器，添加标签组扩展

public class CustomTagGroupFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        var tagGroups = new OpenApiObject
        {
            ["name"] = new OpenApiString("用户管理"),
            ["description"] = new OpenApiString("这是用户相关接口的分组说明，包含注册、登录、信息修改等接口"),
            ["tags"] = new OpenApiArray
            {
                new OpenApiString("User"),
                new OpenApiString("Auth")
            }
        };

        var tagGroupsArray = new OpenApiArray();
        tagGroupsArray.Add(tagGroups);
        
        // 添加到OpenAPI文档的扩展字段
        swaggerDoc.Extensions.Add("x-tagGroups", tagGroupsArray);
    }
}

2. 同样在Program.cs中注册该过滤器

方案3：直接修改Redoc的渲染配置 #

如果需要在Redoc页面的特定位置添加文本，可以在Redoc的初始化脚本中配置props，比如添加自定义的页头或页脚文本：

在你的Redoc页面（通常是~/swagger/index.html或者自定义的HTML页面）中修改Redoc初始化代码：

<script>
    Redoc.init('/swagger/v1/swagger.json', {
        // 其他Redoc配置...
        info: {
            // 覆盖或补充Info部分的文本
            description: '# 自定义全局说明\n这是通过Redoc配置添加的文本'
        }
    }, document.getElementById('redoc-container'));
</script>

常见问题排查 #

• 确保你的Swashbuckle版本是最新的，旧版本可能对OpenAPI 3.0的扩展支持不足
• Redoc只支持标准Markdown语法，避免使用复杂的HTML标签
• 检查生成的swagger.json是否包含你添加的自定义字段，可以通过访问/swagger/v1/swagger.json查看

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