Swashbuckle.aspnetcore: [5.0.0] [.NET CORE 3.0] xml comments not working

[LubosVoska]

Xml comments not working after migration from .net core 2.2 to .net core 3.1 and Swashbuckle.AspNetCore from 4.0.1 to 5.0.0

Configuration:

```c#
services.AddSwaggerGen(c =>
{
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
}

**Error from console**:

System.ArgumentException: The argument 'name' is null, empty or consists only of white-space. (Parameter 'name')
at Microsoft.OpenApi.Writers.OpenApiWriterExtensions.CheckArguments(IOpenApiWriter writer, String name)
at Microsoft.OpenApi.Writers.OpenApiWriterExtensions.CheckArgumentsT
at Microsoft.OpenApi.Models.OpenApiExtensibleDictionary1.SerializeAsV3(IOpenApiWriter writer) at Microsoft.OpenApi.Models.OpenApiOperation.<>c.<SerializeAsV3>b__53_4(IOpenApiWriter w, OpenApiResponses r) at Microsoft.OpenApi.Writers.OpenApiWriterExtensions.WriteRequiredObject[T](IOpenApiWriter writer, String name, T value, Action2 action)
at Microsoft.OpenApi.Models.OpenApiOperation.SerializeAsV3(IOpenApiWriter writer)
at Microsoft.OpenApi.Models.OpenApiPathItem.<>c.b__25_2(IOpenApiWriter w, OpenApiOperation o)
at Microsoft.OpenApi.Writers.OpenApiWriterExtensions.WriteRequiredObjectT
at Microsoft.OpenApi.Models.OpenApiPathItem.SerializeAsV3(IOpenApiWriter writer)
at Microsoft.OpenApi.Models.OpenApiExtensibleDictionary1.<>c.<SerializeAsV3>b__4_0(IOpenApiWriter w, T p) at Microsoft.OpenApi.Writers.OpenApiWriterExtensions.WriteRequiredObject[T](IOpenApiWriter writer, String name, T value, Action2 action)
at Microsoft.OpenApi.Models.OpenApiExtensibleDictionary1.SerializeAsV3(IOpenApiWriter writer) at Microsoft.OpenApi.Models.OpenApiDocument.<>c.<SerializeAsV3>b__32_2(IOpenApiWriter w, OpenApiPaths p) at Microsoft.OpenApi.Writers.OpenApiWriterExtensions.WriteRequiredObject[T](IOpenApiWriter writer, String name, T value, Action2 action)
at Microsoft.OpenApi.Models.OpenApiDocument.SerializeAsV3(IOpenApiWriter writer)
at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.RespondWithSwaggerJson(HttpResponse response, OpenApiDocument swagger)
at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)
```

[chrillejb]

Hi!

I think I have a suggestion that might be worth checking out 😃

The solution only concerns __security requirements__, so if you have none in your swagger generation options I guess this won't be of much help...

Bear in mind that I am no expert in the field of neither Swagger nor Swashbuckle, so this might be totally off the mark but here goes nothing 😛

I was in the exact same situation as you. Upgrading the target framework from: netcoreapp2.2 to: netcoreapp3.1 and coincidentally Swashbuckle.AspNetCore from: 4.0.1 to: 5.0.0.

I encountered the same exception message and a very similar stack trace, although not the exact same trace, but OpenApi was the cause (and it's also the common denominator).

In short, if a OpenApiSecurityRequirement had been added to the swagger generation options the OpenApiSecurityScheme's OpenApiReference's Id needs to be set.

__My configuration:__

swaggerGenOptions.AddSecurityRequirement(new OpenApiSecurityRequirement
{
    {
        new OpenApiSecurityScheme
        {
            Reference = new OpenApiReference
            {
                Id = "Bearer", // <-- Not setting this little bugger caused all my problems...
                Type = ReferenceType.SecurityScheme
            }
        },
        new List<string>()
    }
});

__All of the swagger generation options for clarity:__

services.AddSwaggerGen(swaggerGenOptions =>
{
    swaggerGenOptions.SwaggerDoc(NormalizeTitle(title), new OpenApiInfo
    {
        Title = title,
        Version = Assembly.GetEntryAssembly()?.GetName().Version.ToString()
    });
    // The name of this security definition is linked to the Id below
    swaggerGenOptions.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Description = authorizationToken + " Authentication",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,
        Scheme = "Bearer"
    });
    swaggerGenOptions.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Id = "Bearer",
                    Type = ReferenceType.SecurityScheme
                }
            },
            new List<string>()
        }
    });

    var commentsFile = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, $"{Assembly.GetEntryAssembly()?.GetName().Name}.xml");
    if (!File.Exists(commentsFile))
    {
        throw new Exception($"{nameof(SwaggerExtensions)}: Xml comments file does not exist! ({commentsFile})");
    }
    swaggerGenOptions.IncludeXmlComments(commentsFile);

    // Application specific swagger generation options that have been injected (nvm these)
    options?.Invoke(swaggerGenOptions);
});

(The connection between the Scheme in the security definition and Id in the reference is necessary in order for the authentication to actually work in swagger)

Edit: Seems like I didn't understand the connection properly, my bad! 😛 The Id is connected to the name of the security definition set in the AddSecurityDefinition method (i.e. the first argument fed to the method!). It can be anything as long as they are both the same. Changed mine to "bearer-auth" and it works fine.

The SO link that solved my problem in the end: https://stackoverflow.com/questions/56234504/migrating-to-swashbuckle-aspnetcore-version-5

It can most likely do a better job of explaining the details.

---

My actual stack trace: (for anyone interested)

System.ArgumentException: The argument 'name' is null, empty or consists only of white-space. (Parameter 'name')
   at Microsoft.OpenApi.Writers.OpenApiWriterBase.VerifyCanWritePropertyName(String name)
   at Microsoft.OpenApi.Writers.OpenApiJsonWriter.WritePropertyName(String name)
   at Microsoft.OpenApi.Models.OpenApiReference.SerializeAsV3(IOpenApiWriter writer)
   at Microsoft.OpenApi.Models.OpenApiSecurityScheme.SerializeAsV3(IOpenApiWriter writer)
   at Microsoft.OpenApi.Models.OpenApiSecurityRequirement.SerializeAsV3(IOpenApiWriter writer)
   at Microsoft.OpenApi.Models.OpenApiDocument.<>c.<SerializeAsV3>b__32_4(IOpenApiWriter w, OpenApiSecurityRequirement s)
   at Microsoft.OpenApi.Writers.OpenApiWriterExtensions.WriteCollectionInternal[T](IOpenApiWriter writer, String name, IEnumerable`1 elements, Action`2 action)
   at Microsoft.OpenApi.Writers.OpenApiWriterExtensions.WriteOptionalCollection[T](IOpenApiWriter writer, String name, IEnumerable`1 elements, Action`2 action)
   at Microsoft.OpenApi.Models.OpenApiDocument.SerializeAsV3(IOpenApiWriter writer)
   at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.RespondWithSwaggerJson(HttpResponse response, OpenApiDocument swagger)
   at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)

[zzoller]

Had the same issue with the same stack trace. Ended up tracking it down to an endpoint that had a response xml comment that was missing a code attribute.

changing

/// <response>Successful.</response>

to

/// <response code="200">Successful.</response>

fixed the issue.

[LubosVoska]

Had the same issue with the same stack trace. Ended up tracking it down to an endpoint that had a response xml comment that was missing a code attribute.

changing

/// <response>Successful.</response>

to

/// <response code="200">Successful.</response>

fixed the issue.

Thank you I found same issue in my code.

[ravarnamsft]

@zzoller and @LubosVoska how did you track down the issue? The stack trace isn't very helpful (we are in a similar situation). We do not have response tags like the ones you mentioned, however we have empty return tags . I am not sure which tags cause this error. Did you end up looking at warnings for the generated xml? We do have a lot of cs1591 (missing xml comment for publicly visible member or type) warnings