基于C#类型生成OpenApi 3.0 YAML Schema列表的.NET方案咨询

问题描述 #

需求：

• 生成OpenAPI YAML格式的类型Schema，无需依赖ASP.NET Core控制器，可手动创建OpenAPI 3.0文档
• 从指定C#类型列表生成Schema并放入Components/Schemas以复用
• 需包含目标类型的嵌套类型、基类类型

已尝试技术的局限：

• Microsoft.OpenApi：无基于类型生成Schema的功能
• NSwag、NJsonSchema：默认生成的Schema存于Definitions列表，不符合需求
• Swashbuckle的Swagger.SchemaRegistry：符合复用逻辑，但仅支持Swagger 2.0格式，不满足OpenAPI 3.0要求

提问：.NET环境下是否有类似Swashbuckle的技术，可传入C#类后获取所有关联类型（含嵌套、基类）的OpenAPI 3.0格式Schema列表？

可行解决方案 #

1. 自定义扩展NSwag实现需求 #

NSwag原生支持OpenAPI 3.0，默认生成的Schema会放在definitions节点，但可通过自定义处理将其迁移到components/schemas，同时保留嵌套类型和基类的Schema：

• 使用OpenApiSchemaGenerator生成目标类型的Schema，它会自动收集所有关联类型（嵌套、基类）
• 从SchemaRepository中提取所有生成的Schema，直接放入OpenAPI文档的components/schemas
• 示例代码：

var settings = new OpenApiSchemaGeneratorSettings();
// 配置启用基类、嵌套类型的自动生成
settings.SchemaProcessors.Add(new InheritanceSchemaProcessor());
var generator = new OpenApiSchemaGenerator(settings);

// 生成目标类型的Schema，自动关联所有依赖类型
await generator.GenerateAsync(typeof(YourTargetType));
var allSchemas = generator.SchemaRepository.Schemas;

// 构建符合要求的OpenAPI 3.0文档
var openApiDoc = new OpenApiDocument
{
    Components = new OpenApiComponents
    {
        Schemas = allSchemas
    }
};

// 序列化为YAML格式
var yaml = openApiDoc.ToYaml();

2. 使用Swashbuckle.AspNetCore的Schema生成器（适配OpenAPI 3.0） #

Swashbuckle.AspNetCore完全支持OpenAPI 3.0，可脱离控制器单独使用其Schema生成逻辑：

• 引用Swashbuckle.AspNetCore.SwaggerGen NuGet包
• 手动创建SchemaGenerator和SchemaRepository实例，生成目标类型的Schema时会自动收集嵌套、基类类型
• 示例代码：

var options = new SchemaGeneratorOptions
{
    // 配置启用基类Schema生成、嵌套类型自动发现
    IncludeAllDerivedTypes = true,
    IgnoreObsoleteProperties = false
};
var schemaGenerator = new SchemaGenerator(options);
var schemaRepository = new SchemaRepository();

// 生成目标类型及其关联类型的Schema
schemaGenerator.GenerateSchema(typeof(YourTargetType), schemaRepository);

// 构建OpenAPI 3.0文档，将Schema放入components/schemas
var openApiDoc = new OpenApiDocument
{
    Components = new OpenApiComponents
    {
        Schemas = schemaRepository.Schemas
    }
};

// 序列化为YAML
var yamlSerializer = new YamlSerializer();
var yaml = yamlSerializer.Serialize(openApiDoc);

该方案完全匹配需求：不依赖控制器，生成标准OpenAPI 3.0 Schema，自动包含所有关联类型，且Schema直接对应components/schemas结构。

3. 手动封装Microsoft.OpenApi的类型映射逻辑 #

若需要极致灵活性，可结合.NET的反射或JSON序列化元数据，手动构建OpenAPI 3.0 Schema：

• 编写递归方法，遍历目标类型的属性、基类、嵌套类型
• 逐个将C#类型映射为OpenApiSchema实例，存入components/schemas字典
• 需要自行处理类型转换（如C#值类型→OpenAPI基本类型、Nullable类型、枚举、集合等）

内容的提问来源于stack exchange，提问作者A.K.A.MAGARICH