Swagger Structural error “should NOT have additional properties” $ref element in array

Question

I am getting Structural error "should NOT have additional properties" error due to $ref element present in type: array.

In https://editor.swagger.io when replace $ref: '#/definitions/EnumExample1' with type: array. I do not see the error. But I am not sure how to fix this in swagger-gen code.

If more information is required to understand this issue, please post in comments!

Swagger snippet

  parameters:
    - in: query
      name: parameterNameX
      description: parameterNameX
      type: string
    - in: query
      name: name
      type: string
    - in: query
      name: include
      description: Comma-separated list of properties to include in the response
      type: array
      items:
        $ref: '#/definitions/EnumExample1'

Errors

Structural error at paths./v1/workflows.get.parameters.2.items
should NOT have additional properties
additionalProperty: $ref
Jump to line 30

Startup.cs

 services
                .AddMvc(options =>
                {
                    options.EnableEndpointRouting = false;
                    options.Conventions.Add(new CsvQueryStringConvention());
                })
                .AddNewtonsoftJson(options =>
                {
                    options.SerializerSettings.NullValueHandling = NullValueHandling.Ignore;
                    options.SerializerSettings.DateTimeZoneHandling = DateTimeZoneHandling.Utc;
                    //ensure enums passed to client are strings
                    options.SerializerSettings.Converters.Add(new StringEnumConverter { NamingStrategy = new CamelCaseNamingStrategy()});
                })

 services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("",
                    new OpenApiInfo()
                    {
                        Title = "Service",
                        Version = "v1"
                    });

app.UseSwagger(c =>
            {
                c.RouteTemplate = "app/swagger/{documentName}/swagger.json";
                c.PreSerializeFilters.Add((openApiDocument, httpReq) =>
                {
                    openApiDocument.Servers = new List<OpenApiServer>
                    {
                        new OpenApiServer { Url = $"https://{httpReq.Host.Value}" }
#if DEBUG
                        , new OpenApiServer { Url = $"http://{httpReq.Host.Value}" }
#endif
                    };
                });
                c.SerializeAsV2 = true;
            });

Model

public EnumExample1[] Example { get; set; }

From Swagger Example will be passed as comma-separated string. Since c.SerializeAsV2 = true; I am not sure why generated Swagger.json have $ref element which is OpenApi3 standard.

To recap the linked Q&A: OpenAPI 2.0 array parameters do not support $refs and complex items. You need to define that enum inline. — Helen
Thank you! @Helen My swagger.json is generated on-fly via Startup.cs set up. Could you please help me how to fix this in code? — Nainesh Patel
Do you use Swashbuckle, Swagger-Net or something else? Please post your C# code of the EnumExample1 model and the include parameter, and also your Swashbuckle/Swagger-Net configuration. — Helen
@Helen updated question with more information. I use Swashbuckle — Nainesh Patel

Nainesh Patel Nainesh Patel · Accepted Answer · 2020-07-31T18:01:28

Adding UseInlineDefinitionsForEnums to swagger-gen removed reference to definitions and added type: string.

Found some open issues on swagger and openapi,

OpenAPI.NET : SerializeAsV2 produces invalid swagger (when SerializeAsV3 is valid) [Open]

Swashbuckle.AspNetCore : No type for enums in query parameters (using SerializeAsV2) (Closed with UseInlineDefinitionsForEnums solution)

services.AddSwaggerGen(c =>
            {
                
                c.SwaggerDoc(....);
                
                //Generate inline schema definitions (as opposed to referencing a shared definition) for enum parameters and properties
                c.UseInlineDefinitionsForEnums();

Swagger Structural error “should NOT have additional properties” $ref element in array

1 Answers