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:
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.
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)
@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:
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
Commonlibrary project, I have theMetaclass with this summary:In the
App(asp.net core) project, theWeatherForecastclass has ametaproperty with this summary: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:
This happens because the
XMLfile for theCommonlibrary is loaded after theXMLfile of theApplibrary. 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.