Swagger 结构错误 "should NOT have additional properties" 数组中的 $ref 元素

Question

由于 type: array.

中存在 $ref 元素，我收到结构错误“不应该有其他属性”错误

在https://editor.swagger.io时将$ref: '#/definitions/EnumExample1'替换为type: array。我没有看到错误。但是我不确定如何在 swagger-gen 代码中解决这个问题。

如果需要更多信息来理解这个问题，请在评论中post！

Swagger 代码段

  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'

错误

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

型号

public EnumExample1[] Example { get; set; }

来自 Swagger 的示例将作为逗号分隔的字符串传递。由于 c.SerializeAsV2 = true；我不确定为什么生成的 Swagger.json 具有 OpenApi3 标准的 $ref 元素。

Answer 1

将 UseInlineDefinitionsForEnums 添加到 swagger-gen 中删除了对定义的引用并添加了类型：字符串。

在 swagger 和 openapi 上发现了一些未解决的问题，

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

Swashbuckle.AspNetCore : No type for enums in query parameters (using SerializeAsV2)（使用 UseInlineDefinitionsForEnums 解决方案关闭）

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