小贝子编程

如何使用Swashbuckle在Swagger API文档/OpenAPI规范中包含子类



我在c#中有一个Asp.Net web API 5.2项目，并使用Swashbuckle生成文档。

我有一个包含继承的模型，比如从Animal抽象类中获得Animal属性，以及从中派生的Dog和Cat类

Swashbuckle只显示了Animal类的模式，所以我尝试使用ISchemaFilter（他们也建议这样做），但我无法使其工作，而且我也找不到合适的示例。

有人能帮忙吗？

Swashbuckle似乎没有正确实现多态性，我理解作者关于子类作为参数的观点（如果一个操作需要一个Animal类，并且如果你用狗对象或猫对象调用它，它的行为会有所不同，那么你应该有两个不同的操作…）但作为返回类型，我认为返回Animal和对象可以是Dog或Cat类型。

因此，为了描述我的API并根据正确的指导原则生成正确的JSON模式（请注意我描述判别器的方式，如果你有自己的判别器，你可能需要特别更改该部分），我使用文档和模式过滤器如下：

SwaggerDocsConfig configuration;
.....
configuration.DocumentFilter<PolymorphismDocumentFilter<YourBaseClass>>();
configuration.SchemaFilter<PolymorphismSchemaFilter<YourBaseClass>>();
.....
public class PolymorphismSchemaFilter<T> : ISchemaFilter
{
    private readonly Lazy<HashSet<Type>> derivedTypes = new Lazy<HashSet<Type>>(Init);
    private static HashSet<Type> Init()
    {
        var abstractType = typeof(T);
        var dTypes = abstractType.Assembly
                                 .GetTypes()
                                 .Where(x => abstractType != x && abstractType.IsAssignableFrom(x));
        var result = new HashSet<Type>();
        foreach (var item in dTypes)
            result.Add(item);
        return result;
    }
    public void Apply(Schema schema, SchemaRegistry schemaRegistry, Type type)
    {
        if (!derivedTypes.Value.Contains(type)) return;
        var clonedSchema = new Schema
                                {
                                    properties = schema.properties,
                                    type = schema.type,
                                    required = schema.required
                                };
        //schemaRegistry.Definitions[typeof(T).Name]; does not work correctly in SwashBuckle
        var parentSchema = new Schema { @ref = "#/definitions/" + typeof(T).Name };   
        schema.allOf = new List<Schema> { parentSchema, clonedSchema };
        //reset properties for they are included in allOf, should be null but code does not handle it
        schema.properties = new Dictionary<string, Schema>();
    }
}
public class PolymorphismDocumentFilter<T> : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, System.Web.Http.Description.IApiExplorer apiExplorer)
    {
        RegisterSubClasses(schemaRegistry, typeof(T));
    }
    private static void RegisterSubClasses(SchemaRegistry schemaRegistry, Type abstractType)
    {
        const string discriminatorName = "discriminator";
        var parentSchema = schemaRegistry.Definitions[SchemaIdProvider.GetSchemaId(abstractType)];
        //set up a discriminator property (it must be required)
        parentSchema.discriminator = discriminatorName;
        parentSchema.required = new List<string> { discriminatorName };
        if (!parentSchema.properties.ContainsKey(discriminatorName))
            parentSchema.properties.Add(discriminatorName, new Schema { type = "string" });
        //register all subclasses
        var derivedTypes = abstractType.Assembly
                                       .GetTypes()
                                       .Where(x => abstractType != x && abstractType.IsAssignableFrom(x));
        foreach (var item in derivedTypes)
            schemaRegistry.GetOrRegister(item);
    }
}

前面的代码实现的内容在"支持多态性的模型"一节中有详细说明

{
  "definitions": {
    "Pet": {
      "type": "object",
      "discriminator": "petType",
      "properties": {
        "name": {
          "type": "string"
        },
        "petType": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "petType"
      ]
    },
    "Cat": {
      "description": "A representation of a cat",
      "allOf": [
        {
          "$ref": "#/definitions/Pet"
        },
        {
          "type": "object",
          "properties": {
            "huntingSkill": {
              "type": "string",
              "description": "The measured skill for hunting",
              "default": "lazy",
              "enum": [
                "clueless",
                "lazy",
                "adventurous",
                "aggressive"
              ]
            }
          },
          "required": [
            "huntingSkill"
          ]
        }
      ]
    },
    "Dog": {
      "description": "A representation of a dog",
      "allOf": [
        {
          "$ref": "#/definitions/Pet"
        },
        {
          "type": "object",
          "properties": {
            "packSize": {
              "type": "integer",
              "format": "int32",
              "description": "the size of the pack the dog is from",
              "default": 0,
              "minimum": 0
            }
          },
          "required": [
            "packSize"
          ]
        }
      ]
    }
  }
}

要继续学习Paulo的好答案，如果您使用的是Swagger 2.0，您需要修改类，如图所示：

public class PolymorphismSchemaFilter<T> : ISchemaFilter
{
    private readonly Lazy<HashSet<Type>> derivedTypes = new Lazy<HashSet<Type>>(Init);
    private static HashSet<Type> Init()
    {
        var abstractType = typeof(T);
        var dTypes = abstractType.Assembly
                                 .GetTypes()
                                 .Where(x => abstractType != x && abstractType.IsAssignableFrom(x));
        var result = new HashSet<Type>();
        foreach (var item in dTypes)
            result.Add(item);
        return result;
    }
    public void Apply(Schema model, SchemaFilterContext context)
    {
        if (!derivedTypes.Value.Contains(context.SystemType)) return;
        var clonedSchema = new Schema
        {
            Properties = model.Properties,
            Type = model.Type,
            Required = model.Required
        };
        //schemaRegistry.Definitions[typeof(T).Name]; does not work correctly in SwashBuckle
        var parentSchema = new Schema { Ref = "#/definitions/" + typeof(T).Name };
        model.AllOf = new List<Schema> { parentSchema, clonedSchema };
        //reset properties for they are included in allOf, should be null but code does not handle it
        model.Properties = new Dictionary<string, Schema>();
    }
}
public class PolymorphismDocumentFilter<T> : IDocumentFilter
{
    private static void RegisterSubClasses(ISchemaRegistry schemaRegistry, Type abstractType)
    {
        const string discriminatorName = "discriminator";
        var parentSchema = schemaRegistry.Definitions[abstractType.Name];
        //set up a discriminator property (it must be required)
        parentSchema.Discriminator = discriminatorName;
        parentSchema.Required = new List<string> { discriminatorName };
        if (!parentSchema.Properties.ContainsKey(discriminatorName))
            parentSchema.Properties.Add(discriminatorName, new Schema { Type = "string" });
        //register all subclasses
        var derivedTypes = abstractType.Assembly
                                       .GetTypes()
                                       .Where(x => abstractType != x && abstractType.IsAssignableFrom(x));
        foreach (var item in derivedTypes)
            schemaRegistry.GetOrRegister(item);
    }
    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {
        RegisterSubClasses(context.SchemaRegistry, typeof(T));
    }
}

由于合并到Swashbuckle.AspNetCore中，您可以通过使用获得对多态模式的基本支持

services.AddSwaggerGen(c =>
{
    c.GeneratePolymorphicSchemas();
}

您还可以通过Annotations库中的属性来表达派生类型：

[SwaggerSubTypes(typeof(SubClass), Discriminator = "value")]

本文将进一步详细介绍如何使用Newtonsoft反序列化派生类型。

我想跟进Craig的回答。

如果您使用NSwag从Swagger API文档中生成TypeScript定义，该文档使用Paulo的回答中解释的方法生成，并在Craig的回答中进一步增强，则您可能会面临以下问题：

  1. 生成的TypeScript定义将具有重复的属性，即使生成的类将扩展基类。考虑以下C#类：

    public abstract class BaseClass
{
    public string BaseProperty { get; set; }
}
public class ChildClass : BaseClass
{
    public string ChildProperty { get; set; }
}

    当使用上述答案时，IBaseClass和IChildClass接口的TypeScript定义如下所示：

    export interface IBaseClass {
    baseProperty : string | undefined;
}
export interface IChildClass extends IBaseClass {
    baseProperty : string | undefined;
    childProperty: string | undefined;
}

    正如您所看到的，baseProperty在基类和子类中都被错误地定义。为了解决这个问题，我们可以修改PolymorphismSchemaFilter<T>类的Apply方法，使其只在模式中包含所拥有的属性，即从当前类型模式中排除继承的属性。这里有一个例子：

    public void Apply(Schema model, SchemaFilterContext context)
{
    ...
    // Prepare a dictionary of inherited properties
    var inheritedProperties = context.SystemType.GetProperties()
        .Where(x => x.DeclaringType != context.SystemType)
        .ToDictionary(x => x.Name, StringComparer.OrdinalIgnoreCase);
    var clonedSchema = new Schema
    {
        // Exclude inherited properties. If not excluded, 
        // they would have appeared twice in nswag-generated typescript definition
        Properties =
            model.Properties.Where(x => !inheritedProperties.ContainsKey(x.Key))
                .ToDictionary(x => x.Key, x => x.Value),
        Type = model.Type,
        Required = model.Required
    };
    ...
}

  2. 生成的TypeScript定义不会引用任何现有中间抽象类的属性。考虑以下C#类：

    public abstract class SuperClass
{
    public string SuperProperty { get; set; }
}
public abstract class IntermediateClass : SuperClass
{
     public string IntermediateProperty { get; set; }
}
public class ChildClass : BaseClass
{
    public string ChildProperty { get; set; }
}

    在这种情况下，生成的TypeScript定义如下所示：

    export interface ISuperClass {
    superProperty: string | undefined;
}        
export interface IIntermediateClass extends ISuperClass {
    intermediateProperty : string | undefined;
}
export interface IChildClass extends ISuperClass {
    childProperty: string | undefined;
}

    请注意生成的IChildClass接口是如何直接扩展ISuperClass的，而忽略了IIntermediateClass接口，从而有效地使IChildClass的任何实例都没有intermediateProperty属性。

    我们可以使用以下代码来解决这个问题：

    public void Apply(Schema model, SchemaFilterContext context)
{
    ...
    // Use the BaseType name for parentSchema instead of typeof(T), 
    // because we could have more classes in the hierarchy
    var parentSchema = new Schema
    {
        Ref = "#/definitions/" + (context.SystemType.BaseType?.Name ?? typeof(T).Name)
    };
    ...
}

    这将确保子类正确地引用中间类。

总之，最后的代码看起来是这样的：

    public void Apply(Schema model, SchemaFilterContext context)
    {
        if (!derivedTypes.Value.Contains(context.SystemType))
        {
            return;
        }
        // Prepare a dictionary of inherited properties
        var inheritedProperties = context.SystemType.GetProperties()
            .Where(x => x.DeclaringType != context.SystemType)
            .ToDictionary(x => x.Name, StringComparer.OrdinalIgnoreCase);
        var clonedSchema = new Schema
        {
            // Exclude inherited properties. If not excluded, 
            // they would have appeared twice in nswag-generated typescript definition
            Properties =
                model.Properties.Where(x => !inheritedProperties.ContainsKey(x.Key))
                    .ToDictionary(x => x.Key, x => x.Value),
            Type = model.Type,
            Required = model.Required
        };
        // Use the BaseType name for parentSchema instead of typeof(T), 
        // because we could have more abstract classes in the hierarchy
        var parentSchema = new Schema
        {
            Ref = "#/definitions/" + (context.SystemType.BaseType?.Name ?? typeof(T).Name)
        };
        model.AllOf = new List<Schema> { parentSchema, clonedSchema };
        // reset properties for they are included in allOf, should be null but code does not handle it
        model.Properties = new Dictionary<string, Schema>();
    }

我们最近升级到.NET Core 3.1和Swashbuckle.AspNetCore 5.0API也有所改变。如果有人需要这个过滤器，这里是代码的最小变化，以获得类似的行为：

public class PolymorphismDocumentFilter<T> : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        RegisterSubClasses(context.SchemaRepository, context.SchemaGenerator, typeof(T));
    }
    private static void RegisterSubClasses(SchemaRepository schemaRegistry, ISchemaGenerator schemaGenerator, Type abstractType)
    {
        const string discriminatorName = "$type";
        OpenApiSchema parentSchema = null;
        if (schemaRegistry.TryGetIdFor(abstractType, out string parentSchemaId))
            parentSchema = schemaRegistry.Schemas[parentSchemaId];
        else
            parentSchema = schemaRegistry.GetOrAdd(abstractType, parentSchemaId, () => new OpenApiSchema());
        // set up a discriminator property (it must be required)
        parentSchema.Discriminator = new OpenApiDiscriminator() { PropertyName = discriminatorName };
        parentSchema.Required = new HashSet<string> { discriminatorName };
        if (parentSchema.Properties == null)
            parentSchema.Properties = new Dictionary<string, OpenApiSchema>();
        if (!parentSchema.Properties.ContainsKey(discriminatorName))
            parentSchema.Properties.Add(discriminatorName, new OpenApiSchema() { Type = "string", Default = new OpenApiString(abstractType.FullName) });
        // register all subclasses
        var derivedTypes = abstractType.GetTypeInfo().Assembly.GetTypes()
            .Where(x => abstractType != x && abstractType.IsAssignableFrom(x));
        foreach (var item in derivedTypes)
            schemaGenerator.GenerateSchema(item, schemaRegistry);
    }
}
public class PolymorphismSchemaFilter<T> : ISchemaFilter
{
    private readonly Lazy<HashSet<Type>> derivedTypes = new Lazy<HashSet<Type>>(Init);
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (!derivedTypes.Value.Contains(context.Type)) return;
        Type type = context.Type;
        var clonedSchema = new OpenApiSchema
        {
            Properties = schema.Properties,
            Type = schema.Type,
            Required = schema.Required
        };
        // schemaRegistry.Definitions[typeof(T).Name]; does not work correctly in Swashbuckle.AspNetCore
        var parentSchema = new OpenApiSchema
        {
            Reference = new OpenApiReference() { ExternalResource = "#/definitions/" + typeof(T).Name }
        };
        var assemblyName = Assembly.GetAssembly(type).GetName();
        schema.Discriminator = new OpenApiDiscriminator() { PropertyName = "$type" };
        // This is required if you use Microsoft's AutoRest client to generate the JavaScript/TypeScript models
        schema.Extensions.Add("x-ms-discriminator-value", new OpenApiObject() { ["name"] = new OpenApiString($"{type.FullName}, {assemblyName.Name}") });
        schema.AllOf = new List<OpenApiSchema> { parentSchema, clonedSchema };
        // reset properties for they are included in allOf, should be null but code does not handle it
        schema.Properties = new Dictionary<string, OpenApiSchema>();
    }
    private static HashSet<Type> Init()
    {
        var abstractType = typeof(T);
        var dTypes = abstractType.GetTypeInfo().Assembly
            .GetTypes()
            .Where(x => abstractType != x && abstractType.IsAssignableFrom(x));
        var result = new HashSet<Type>();
        foreach (var item in dTypes)
            result.Add(item);
        return result;
    }
}

我没有完全检查结果，但它似乎给出了相同的行为。

还要注意，您需要导入以下名称空间：

using Microsoft.OpenApi.Models;
using Microsoft.OpenApi.Any;
using System.Reflection;
using Swashbuckle.AspNetCore.SwaggerGen;

这适用于5.6.3:版本

services.AddSwaggerGen(options =>
{
    options.UseOneOfForPolymorphism();
    options.SelectDiscriminatorNameUsing(_ => "type");
});

相关内容

最新更新


热门标签：

javascript python java c# php android html jquery c++ css ios sql mysql arrays asp.net json python-3.x ruby-on-rails .net sql-server django objective-c excel regex ruby linux ajax iphone xml vba spring asp.net-mvc database wordpress string postgresql wpf windows xcode bash git oracle list vb.net multithreading eclipse algorithm macos powershell visual-studio image forms numpy scala function api selenium