如何在swagger.json中添加额外未通过控制器暴露的model定义？

以下是不同技术栈下无需创建伪控制器即可暴露未被接口引用的Model到接口契约的可行方案：

1. Swashbuckle（ASP.NET Core 常用Swagger/OpenAPI生成库） #

直接通过内置扩展+自定义过滤器实现即可：

• 第一步：在项目属性「生成」选项卡中开启「XML文档文件」生成，建议同时勾选「取消显示XML注释警告」避免编译告警
• 第二步：在Swagger配置段添加XML注释引入，第二个参数设为true即可默认包含所有公共类型的注释，额外添加自定义SchemaFilter批量注册未被引用的Model：

builder.Services.AddSwaggerGen(options =>
{
    var xmlPath = Path.Combine(AppContext.BaseDirectory, "你的项目名称.xml");
    // 第二个参数为true时会加载控制器以外的公共类型注释
    options.IncludeXmlComments(xmlPath, true);
    // 注册自定义过滤器批量添加额外Model
    options.SchemaFilter<AddExtraModelsSchemaFilter>();
});

• 自定义SchemaFilter示例（可按命名空间、自定义注解等规则筛选需要暴露的Model）：

public class AddExtraModelsSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 示例：扫描指定命名空间下所有公共非抽象类
        var modelTypes = Assembly.GetExecutingAssembly()
            .GetTypes()
            .Where(t => t.Namespace == "你的Models命名空间" && t.IsPublic && !t.IsAbstract);
        
        foreach (var type in modelTypes)
        {
            if (!context.SchemaRepository.Schemas.ContainsKey(type.Name))
            {
                context.SchemaGenerator.GenerateSchema(type, context.SchemaRepository);
            }
        }
    }
}

2. SpringDoc（Java SpringBoot 常用OpenAPI生成库） #

两种方案可选：

• 方案1：直接在启动类/配置类上通过注解显式指定需要暴露的Model

@OpenAPIDefinition(
    extraSchemas = {
        @Schema(implementation = UserModel.class),
        @Schema(implementation = OrderModel.class)
    }
)
@SpringBootApplication
public class DemoApplication {}

• 方案2：自定义配置类批量扫描符合规则的Model自动注册

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        OpenAPI openApi = new OpenAPI();
        // 示例：扫描指定包下所有带@Schema注解的类
        Reflections reflections = new Reflections("com.yourproject.models");
        Set<Class<?>> modelClasses = reflections.getTypesAnnotatedWith(Schema.class);
        for (Class<?> clazz : modelClasses) {
            openApi.getComponents().addSchemas(clazz.getSimpleName(), 
                ModelConverters.getInstance().readAllAsResolvedSchema(clazz).schema);
        }
        return openApi.info(new Info().title("接口文档").version("1.0"));
    }
}

3. 通用适配规则 #

几乎所有接口契约生成工具都支持两类扩展逻辑，无需创建伪控制器：

• 自定义Schema扩展点：所有生成工具都会预留Schema生成阶段的扩展入口，你可以在该阶段按照自定义规则（命名空间、自定义注解、类名前缀等）批量将需要暴露的Model添加到契约的Schema列表中
• 显式Schema注册：绝大多数工具都提供手动注册Schema的API，你可以逐个/批量将目标Model注册到生成器的Schema仓库，生成契约时会自动包含这些类型的定义

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