Comment inclure des sous-classes dans la documentation de l'API Swagger / spécification OpenAPI à l'aide de Swashbuckle?

Question

J'ai un projet d'API web Asp.Net 5.2 en c # et je génère de la documentation avec Swashbuckle.

J'ai un modèle qui contient quelque chose d'héritage comme avoir une propriété animale d'une classe abstraite animale et des classes de chien et de chat qui en dérivent.

Swashbuckle ne montre que le schéma de la classe Animal, j'ai donc essayé de jouer avec ISchemaFilter (c'est ce qu'ils suggèrent aussi) mais je n'ai pas pu le faire fonctionner et je ne trouve pas non plus d'exemple approprié.

Quelqu'un peut-il aider?

Answer 1

Il semble que Swashbuckle n'implémente pas correctement le polymorphisme et je comprends le point de vue de l'auteur sur les sous-classes en tant que paramètres (si une action attend une classe animale et se comporte différemment si vous l'appelez avec un objet chien ou un objet chat, alors vous devriez ont 2 actions différentes ...) mais en tant que types de retour, je crois qu'il est correct de retourner Animal et les objets peuvent être de type chien ou chat.

Donc, pour décrire mon API et produire un schéma JSON approprié conformément aux directives correctes (soyez conscient de la façon dont je décris le discriminateur, si vous avez votre propre discriminateur, vous devrez peut-être modifier cette partie en particulier), j'utilise des filtres de document et de schéma comme suit:

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);
    }
}

Ce que le code précédent implémente est spécifié ici , dans la section "Modèles avec prise en charge du polymorphisme. Il produit essentiellement quelque chose comme ceci:

{
  "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"
          ]
        }
      ]
    }
  }
}

Answer 2

Pour faire suite à la grande réponse de Paulo, si vous utilisez Swagger 2.0, vous devrez modifier les classes comme indiqué:

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));
    }
}

Answer 3

J'aimerais poursuivre sur la réponse de Craig.

Si vous utilisez NSwag pour générer des définitions TypeScript à partir de la documentation de l'API Swagger générée avec Swashbuckle (3.x au moment de la rédaction) en utilisant la méthode expliquée dans Réponse de Paulo et encore améliorée dans Réponse de Craig vous rencontrerez probablement les problèmes suivants:

1. Les définitions TypeScript générées auront des propriétés en double même si les classes générées étendent les classes de base. Considérez les classes C # suivantes:

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

   Lors de l'utilisation des réponses susmentionnées, la définition TypeScript résultante des interfaces IBaseClass et IChildClass ressemblerait à ceci:

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

   Comme vous pouvez le voir, le baseProperty n'est pas défini correctement dans les classes de base et enfant. Pour résoudre ce problème, nous pouvons modifier la méthode Apply de la PolymorphismSchemaFilter<T> classe pour inclure uniquement les propriétés possédées dans le schéma, c'est-à-dire pour exclure les propriétés héritées du schéma des types actuels. Voici un exemple:

   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. Les définitions TypeScript générées ne référenceront pas les propriétés des classes abstraites intermédiaires existantes. Considérez les classes C # suivantes:

   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; }
   }
   

   Dans ce cas, les définitions TypeScript générées devraient ressembler à ceci:

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

   Remarquez comment l'interface IChildClass générée étend directement ISuperClass, ignorant l'interface IIntermediateClass, laissant efficacement toute instance de IChildClass sans la propriété intermediateProperty .

   Nous pouvons utiliser le code suivant pour résoudre ce problème:

   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)
       };
   
       ...
   }
   

   Cela garantira que la classe enfant référence correctement la classe intermédiaire.

En conclusion, le code final ressemblerait alors à ceci:

    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>();
    }

Answer 4

Nous avons récemment mis à niveau vers .NET Core 3.1 et Swashbuckle.AspNetCore 5.0 Et l'API a été quelque peu modifiée. Au cas où quelqu'un aurait besoin de ce filtre, voici le code avec des changements minimes pour obtenir un comportement similaire:

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;
    }
}

Je n'ai pas inspecté complètement le résultat, mais il semble qu'il donne le même comportement.

Notez également que vous devez importer ces espaces de noms:

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