如何在Swagger中暴露未被控制器API接口引用的Schema类

Swagger默认仅自动扫描暴露所有被API控制器引用的Schema，未被引用的类需要手动配置才会出现在Schema列表中。示例中需要暴露的Song类代码如下：

using System;
namespace ExampleNamespace
{
    public class Song
    {
        [Key][Required]
        public int SongID { get; set; }
        [Required]
        public string SongName { get; set; }
        public string SongDescription { get; set; }
        public int SongLength { get; set; } //seconds
        [Required]
        public int AlbumID { get; set; }
    }
}

现有已展示的Swagger Schema列表示例：

下面是不同场景下的实现方案：

方案1：直接在Swagger配置中映射类型（最简便，适合少量类） #

如果你使用的是主流的Swashbuckle.AspNetCore库，直接在Program.cs（.NET 6+）或Startup.cs的Swagger服务注册配置中添加MapType配置即可：

// 需先引入命名空间
using Microsoft.OpenApi.Models;

builder.Services.AddSwaggerGen(options =>
{
    // 你原有的Swagger配置，比如定义文档信息、加JWT认证配置等
    options.MapType<Song>(() => new OpenApiSchema 
    { 
        Reference = new OpenApiReference 
        { 
            Type = ReferenceType.Schema, 
            Id = nameof(Song) 
        } 
    });
});

方案2：自定义Schema过滤器（适合批量注册多个类） #

如果有多个未被引用的Schema需要暴露，自定义过滤器统一管理更方便：

1. 首先创建过滤器类：

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

public class ExposeCustomSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 把所有需要额外暴露的类都加在下面的列表里
        var exposeTypes = new List<Type> { typeof(Song) /*, typeof(其他类), typeof(其他类2)*/ };
        if (exposeTypes.Contains(context.Type))
        {
            context.SchemaGenerator.GenerateSchema(context.Type, context.SchemaRepository);
        }
    }
}

2. 在Swagger配置中注册该过滤器：

builder.Services.AddSwaggerGen(options =>
{
    // 原有配置
    options.SchemaFilter<ExposeCustomSchemaFilter>();
});

方案3：NSwag库配置 #

如果你使用的是NSwag.AspNetCore库，配置更简单，直接在注册OpenApi文档时添加对应类型即可：

builder.Services.AddOpenApiDocument(options =>
{
    // 原有配置
    options.AddType<Song>();
});

内容的提问来源于stack exchange，提问作者Cardi DeMonaco Jr