Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SwaggerGenOptions.IncludeXmlComments does not support /// <inheritdoc /> #2597

Open
Sour-Codes opened this issue Jan 26, 2023 · 5 comments
Open
Labels
feature suggestion help-wanted A change up for grabs for contributions from the community

Comments

@Sour-Codes
Copy link

To replicate:

  1. Create a new ASP.NET Core Web API project.

dotnet new webapi

  1. Set <GenerateDocumentationFile> to true in .csproj.

  2. In Program.cs, replace builder.Services.AddSwaggerGen(); with:


builder.Services.AddSwaggerGen(
    swaggerGenConfiguration =>
    {
        var assembly = System
            .Reflection
            .Assembly
            .GetExecutingAssembly()
            ;
        var assemblyName = assembly
            .GetName()
            .Name
            ;
		var xmlFile = $"{assemblyName}.xml";
		var xmlPath = Path.Combine(
			AppContext.BaseDirectory,
			xmlFile
		);

        swaggerGenConfiguration.IncludeXmlComments(
            xmlPath
        );
    }
);

  1. Insert the following before [HttpGet(Name = "GetWeatherForecast")]:

/// <summary>
///     This is my XML documentation comment!
/// </summary>

  1. Modify [HttpGet(Name = "GetWeatherForecast")] with the following:

[HttpGet("GetWeatherForecast")]

  1. Create a new type that extends WeatherForecastController, such as:

/// <summary>
///     Extends <see cref="WeatherForecastController" />.
/// </summary>
public class WeatherForecastController2
    : WeatherForecastController
{
    /// <summary>
    ///     Create a new instance.
    /// </summary>
    /// <param name="logger">
    ///     The logger.
    /// </param>
	public WeatherForecastController2(
		ILogger<WeatherForecastController> logger
	)
		: base(
			logger
		)
	{

	}

	/// <inheritdoc />
	public override IEnumerable<WeatherForecast> Get()
		=> base.Get();
}

  1. Run the project

dotnet run

  1. Navigate to Swagger UI.
  2. Observe how the deriving type does not show the XML documentation comment with the action.
  3. Replace the XML documentation of the deriving type with the following:

/// <summary>
///     This is my XML documentation comment without inheriting from the base type!
/// </summary>

  1. Run the project

dotnet run

  1. Observe how the deriving type does show the replaced XML documentation comment with the action.
@songzheng45
Copy link

I switched to NSwag in the end.

@dotjpg3141
Copy link

dotjpg3141 commented Oct 5, 2023

There are some workarounds in domaindrivendev/Swashbuckle.WebApi#1000 for ASP.NET Core

@Havunen
Copy link

Havunen commented Feb 22, 2024

FYI this is supported in DotSwashbuckle

@fprdkhti
Copy link

fprdkhti commented Apr 6, 2024

I still can't use inheritdoc functionality when it inherits xml document from another assembly.
thanks for any help.

@martincostello martincostello added feature suggestion help-wanted A change up for grabs for contributions from the community labels Apr 14, 2024
@Chaosflo
Copy link

Any news when this will be pushed?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature suggestion help-wanted A change up for grabs for contributions from the community
Projects
None yet
Development

Successfully merging a pull request may close this issue.

7 participants