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

Question

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

Pao*_*ori 19 c# api subclassing swagger openapi

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

我有一个包含继承的模型,比如从Animal抽象类中获取Animal属性,从中派生出Dog和Cat类.

Swashbuckle只显示Animal类的模式,所以我尝试使用ISchemaFilter(他们也建议),但我无法使它工作,我也找不到合适的例子.

有人可以帮忙吗？

Answer 1

Pao*_*ori 27

似乎Swashbuckle没有正确实现多态性,我理解作者关于子类作为参数的观点(如果一个动作需要一个Animal类,如果用dog对象或cat对象调用它,行为会有所不同,那么你应该有2个不同的动作...)但作为返回类型我相信返回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);
    }
}

归档时间：	9 年，11 月前
查看次数：	10225 次
最近记录：	6 年，6 月前