Swashbuckle how to add OneOf declaration to OpenAPI 3

Question

I have a request object that can be of 2 string types "A" or "B".

Note: This is a simpler example of what I really want. An enum won't work for me here.

public class SampleRequest
    {
        //Can only be "A" or "B"
        public string Property1 { get; set; }
    }

I am trying to create a schema filter that can output as the OpenAPI "OneOf" attribute.

https://datatracker.ietf.org/doc/html/draft-fge-json-schema-validation-00#section-5.5.5

https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/#oneof

https://github.com/domaindrivendev/Swashbuckle.AspNetCore#schema-filters

public class CustomSchemaFilter : ISchemaFilter
    {
        public void Apply(OpenApiSchema schema, SchemaFilterContext context)
        {

            schema.OneOf = new List<OpenApiSchema>
            {

                new OpenApiSchema {Type = "string", Description = "A"},
                new OpenApiSchema {Type = "string", Description = "B"}
            };
            
        }
    }

When running the swagger, swagger-ui correctly renders the "oneOf" description:

oneOf: List [ OrderedMap { "type": "string", "description": "A" }, OrderedMap { "type": "string", "description": "B" } ]

However, I was expecting the value of it to look more like

oneOf: [ "A", "B" ]

Is this possible? The people reading my swagger documentation aren't going to know what a List of OrderedMap is.

not sure what is your question here? – lordrhodos Sep 17 '20 at 21:55 — lordrhodos, Sep 17 '20 at 21:55

score 8 · Answer 1 · edited Sep 17 '21 at 19:07

8

In C# .NET Core 5: In order to automatically resolve oneOf (polymorphism) at compile-time for your swagger.json, add the following line in your Startup.cs:

public void ConfigureServices(IServiceCollection services){
     services.AddSwaggerGen(c => {c.UseOneOfForPolymorphism();})
}

For everything else, you can follow the documentation of OpenAPI 3.0.

edited Sep 17 '21 at 19:07

Jeremy Caney

7,102
69
48
77

answered Sep 17 '21 at 17:16

Julien Green

89
1
6

score 0 · Answer 2 · answered Mar 29 '23 at 21:53

I solve this with a SchemaFilter:

    public class SampleRequest
    {
        //Can only be "A" or "B"
        public string Property1 { get; set; }
    }
    public class SampleRequestSchemaFilter : ISchemaFilter
    {
        public void Apply(
            OpenApiSchema schema,
            SchemaFilterContext context
        )
        {
            if (context.Type == typeof(SampleRequest))
            {
                var sampleProperty = schema.Properties.FirstOrDefault(
                    c => string.Equals(
                        c.Key,
                        nameof(SampleRequest.Property1),
                        StringComparison.InvariantCultureIgnoreCase
                    )
                );
                if (sampleProperty.Value != null)
                {
                    var oneOfList = new List<OpenApiSchema>();
                    var aSchema = context.SchemaGenerator.GenerateSchema(typeof(A),context.SchemaRepository);
                    if (aSchema != null)
                    {
                        oneOfList.Add(aSchema);
                    }
                    var bSchema = context.SchemaGenerator.GenerateSchema(typeof(B),context.SchemaRepository);
                    if (bSchema != null)
                    {
                        oneOfList.Add(bSchema);
                    }
                    if (oneOfList.Any())
                    {
                        var oneOfSchema = new OpenApiSchema
                        {
                            Type = "object",
                            OneOf = oneOfList
                        };
                        schema.Properties.Remove(sampleProperty.Key);
                        schema.Properties.Add(sampleProperty.Key, oneOfSchema);
                    }
                }
            }
        }
    }

Im using this version of the package:

    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.2.3" />

Swashbuckle how to add OneOf declaration to OpenAPI 3

2 Answers2

Linked