ASP.NET Core中Swashbuckle能否添加非接口关联的独立文档？

这个问题问得好！Swashbuckle完全支持添加架构文档、示例应用这类和接口无关的内容，而且不需要跳转到外部页面，能完美复用Swagger UI的样式和布局。下面给你几个实用的实现方案：

方案1：自定义Swagger UI首页，注入额外内容 #

Swagger UI的首页是可以自定义的，你可以修改默认的index.html，在合适的位置（比如接口列表上方或侧边）添加专属的文档区块，完全沿用Swagger的样式。

步骤如下：

1. 在项目中添加一个自定义的CustomIndex.html文件，把Swagger默认的index.html内容复制过来（可以直接访问你的Swagger页面右键查看源代码获取）。
2. 在自定义的HTML里插入你的架构文档或示例应用说明，比如在<div id="swagger-ui">之前添加一个新的section：

<div class="swagger-ui-section">
  <h2>架构文档</h2>
  <div class="markdown">
    ### 系统分层架构
    我们的API采用Clean Architecture设计，分为三层：
    - **表现层**：ASP.NET Core Web API控制器，负责接收请求和返回响应
    - **业务逻辑层**：处理核心业务规则的服务类
    - **数据访问层**：与数据库交互的仓储实现

    ### 核心技术栈
    - ASP.NET Core 8
    - Entity Framework Core 8
    - Redis 分布式缓存
  </div>
</div>

3. 在Program.cs中配置Swagger UI时，指定使用自定义的首页：

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "我的API V1");
    // 替换为自定义首页的资源流，注意修改命名空间为你的项目命名空间
    options.IndexStream = () => typeof(Program).Assembly.GetManifestResourceStream("YourProjectNamespace.CustomIndex.html");
});

注意要把CustomIndex.html的“生成操作”设置为“嵌入的资源”，这样才能通过程序集读取到。

方案2：用文档过滤器添加“伪接口”式文档 #

你可以创建一个不实际处理请求的“伪接口”，把它作为文档页面展示，这种方式会自动融入Swagger的接口列表，样式完全统一。

比如创建一个架构文档的过滤器：

public class ArchitectureDocFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // 创建一个虚拟的操作，用来展示架构文档
        var architectureDoc = new OpenApiOperation
        {
            Summary = "系统架构概述",
            Description = @"
### 架构设计原则
- 依赖倒置：上层模块不依赖下层模块，两者都依赖抽象
- 单一职责：每个类只负责一个功能领域
- 开闭原则：对扩展开放，对修改关闭

### 部署架构
API采用容器化部署，通过Kubernetes管理，包含以下组件：
- 主API服务
- Redis缓存集群
- PostgreSQL数据库
- ELK日志系统
",
            Responses = new OpenApiResponses
            {
                ["200"] = new OpenApiResponse { Description = "文档内容" }
            }
        };

        // 把这个虚拟操作添加到一个自定义路径下
        swaggerDoc.Paths.Add("/docs/architecture", new OpenApiPathItem
        {
            Get = architectureDoc
        });
    }
}

然后在Swagger注册时添加这个过滤器：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "我的API", Version = "v1" });
    c.DocumentFilter<ArchitectureDocFilter>();
});

这样在Swagger UI里，你会看到一个/docs/architecture的接口，点击进去就能看到完整的架构文档，样式和普通接口完全一致。

方案3：利用标签（Tags）分组展示文档 #

你可以把非接口文档作为一个独立的标签，在标签的描述里添加详细内容，这种方式适合把相关文档和接口分组管理。

示例代码：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "我的API", Version = "v1" });
    
    // 添加自定义标签
    c.TagActionsBy(api => new List<string> { "示例应用指南" });
    
    // 给标签添加详细描述
    c.DocumentFilter<SampleAppTagFilter>();
});

public class SampleAppTagFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        swaggerDoc.Tags.Add(new OpenApiTag
        {
            Name = "示例应用指南",
            Description = @"
### Web客户端示例
基于React的Web应用，演示如何调用API的用户管理接口，包含登录、用户列表、详情查看等功能。

### 移动端示例
基于MAUI的跨平台应用，展示API的离线同步能力，支持无网络时缓存数据，联网后自动同步。

### 运行示例步骤
1. 克隆项目内部仓库的代码
2. 进入对应示例文件夹，按照README配置依赖
3. 启动API服务后，运行示例应用即可测试
"
        });
    }
}

在Swagger UI里，点击顶部的“示例应用指南”标签，就能看到完整的文档内容，样式和接口标签的描述完全统一。

这三个方案都能满足你的需求，不需要跳转到外部页面，完美复用Swagger的视觉风格。你可以根据自己的文档复杂度选择合适的方式~

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