XML comments <remarks> not included in swagger.json for DTO properties

[mabead]

I am using version 13.7.0 of NSwag.AspNetCore. With this, I have a DTO that is documented like this:

// In controller
[OpenApiOperation("GetMetadata")]
[ProducesResponseType(typeof(UserMetadataResponse), 200)]
public async Task<IActionResult> GetMetadata()
{
  // ...
}

public class UserMetadataResponse
{
    /// ...
	
    /// <summary>
    /// Indicates which version of each service offer that the user currently has access to.
    /// </summary>
    public ServiceOffersVersionDto ServiceOffersVersion { get; private set; }
}

public class ServiceOffersVersionDto
{
	/// <summary>
	/// The version of the 'FooBar' service offer.
	/// </summary>
	/// <remarks>
	/// The possible values are:
	/// * null: bla bla
	/// * -1: foo bar
	/// * 1: xyz
	/// </remarks>
	public int? FooBar { get; set; }
}

Then, when I start my ASP.Net service and look at the resulting swagger.json, I get this:

As you can see, my <summary> properly ends up in the generated swagger.json but my <remarks> are lost.

Is this a known limitation? Am I missing something for my <remarks> to end up in the swagger.json file?

[RicoSuter]

I think the reason is that OpenAPI/Swagger does not have a property where we could map this to. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject

[mabead]

Ok. @RicoSuter since the OpenAPI/swagger specification does not allow it, would it be an option for nswag to concatenate the <summary> and <remarks> text to fill the OpenAPI/swagger description property?

[RicoSuter]

You can do that with a custom operation processer and the Namotion.Reflection library (which is automatically available when referencing the NSwag library). Adding it out-of-the-box would be a "breaking change" and a too opinionated implementation.

[Peter-Svahn]

Hi, could you please outline how to do this? I think that having the XML comments from the controller available in the generated client code too.