Swashbuckle.AspNetCore: [Bug]: Description of a property shows the summary of the underlying class instead of the property summary

Describe the bug

In the Swagger documentation, descriptions of properties derived from classes always show the information from the <summary> of the class, not the <summary> of the property. For example, here is the definition of the slightly altered WeatherForecast demo project’s WeatherForecast class:

/// <summary>
/// Weather forecast info.
/// </summary>
public class WeatherForecast
{
    /// <summary>
    ///  City name.
    /// </summary>
    public string? City { get; set; }

    /// <summary>
    /// Forecast date.
    /// </summary>
    public DateOnly Date { get; set; }

    /// <summary>
    /// Forecast summary.
    /// </summary>
    public string? Summary { get; set; }

    /// <summary>
    /// Forecasted temperature in the specified city.
    /// </summary>
    public Temperature? Temperature { get; set; }
}

The Temperature property is a complex type defined as:

/// <summary>
/// Holds temperature in Celsius and Fahrenheit.
/// </summary>
public class Temperature
{
    /// <summary>
    /// Temperature in C.
    /// </summary>
    public int TemperatureC { get; set; }

    /// <summary>
    /// Temperature in F.
    /// </summary>
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Notice that the summary of the Temperature property in the WeatherForecast class (Forecasted temperature in the specified city.) is different from the summary of the Temperature class definition (Holds temperature in Celsius and Fahrenheit.), but when displayed in the Swagger documentation, the summary of the property is discarded, so only the class summary is displayed:

Image

The problem is that the class summary is not specific enough to describe a property derived from this class. It may not be obvious in this example, but say, I have a meta class that defines the details of a patch operation for patching objects and I want to specify which patch operations are supported for each class. This can be only be done in the summary of the property, not in the class summary (because the class does not know where and how it will be used), right? But there seems to be no way to do it.

Attached is the sample project.

Expected behavior

Swagger description of a schema’s (class) property must always contain the summary of this property as defined in the containing schema (class), not the summary of the class (schema) that this property is derived from.

Actual behavior

Swagger description of a schema’s (class) property always shows the summary of the class (schema) that this property is derived from, not the property’s summary.

Steps to reproduce

Use the attached project.

TestSwagger.zip

Exception(s) (if any)

No response

Swashbuckle.AspNetCore version

7.2.0

.NET Version

9.0.102

Anything else?

No response

About this issue

  • Original URL
  • State: open
  • Created 2 years ago
  • Comments: 26 (10 by maintainers)

Commits related to this issue

Most upvoted comments

@alekdavis you commented the UseAllOfToExtendReferenceSchemas part

The problem you have is the code you wrote. Every time you are calling IncludeXmlComments you are inserting the ParameterFilter/RequestBodyFilter/OperationFilter/SchemaFilter/DocumentFilter associated to the Assembly at hand, and every assembly could override the other one.

I just applied this thing:

if (xmlFiles != null && xmlFiles.Count > 0)
{
	XDocument fullXmlDoc = new(new XElement(XName.Get("doc")));
	var fullXmlMembers = new XElement(XName.Get("members"));

	if (fullXmlDoc.Root is not null)
	{
		xmlFiles.ForEach(xmlFile =>
		{
			var xDocument = XDocument.Load(xmlFile);
			var assemblyMembers = xDocument.Root?.Element(fullXmlMembers.Name);
			if (assemblyMembers is not null)
			{
				foreach (var assemblymember in assemblyMembers.Elements())
				{
					fullXmlMembers.Add(assemblymember);
				}
			}
		});
		fullXmlDoc.Root.Add(fullXmlMembers);
	}
	options.IncludeXmlComments(() => new XPathDocument(fullXmlDoc.CreateReader()), true);
	options.UseAllOfToExtendReferenceSchemas();
}

And right now it seems to work fine(I know it seems to be a WorkAround, but the problem that you are having is that the Filters do not have the full information to load everything. This way you end up having just a filter with all assemblies information and this way seems to work

I think this is nice to have in the docs as well, because this issue could be happening to more people.

@alekdavis try this yourself

@jgarciadelanoceda Welcome back. 😃 I created a demo repo at https://github.com/alekdavis/swagger-bug-demo. There are several things that I can show, but I’m starting with the base scenario. I can do updates to illustrate the progression of how things get fixed and broken. Anyway, in this version, I am illustrating the summary of the property being overwritten by the summary of the class.

In the Common library project, I have the Meta class with this summary:

Image

In the App (asp.net core) project, the WeatherForecast class has a meta property with this summary:

Image

In the Swagged documentation, the property summary should be displayed (since the property summary is specific to the object and the summary of the type (class) would be too generic), but it shows the class (type), not the property, summary:

Image

This happens because the XML file for the Common library is loaded after the XML file of the App library. If you change the load order (using timestamps, renaming files, etc), then it would show the property summary, as it should.

So, this is problem number 1, but there are more. 😉

I am back again after the paternity leave, can you create a minimal GitHub project where I can see the behaviour? It will be much easier

Sorry for the delay, I couldn’t do it for now, because I have been taking care of a new child, I will look at it when I can

I’ll look into it. It’s possible that #3136 is related

Please provide a minimal example, if it’s possible a gh repo with the minimal things possible

@alekdavis it seems that it was reported and fixed see #2379. I will look into it by the way

I have a very vague memory of noticing this before I was a maintainer of Swashbuckle, and digging into it and finding it was something to do with how the internals of Microsoft.OpenApi works, but I could be misremembering.