Swagger - How to add definitions on child objects in c#

Question

In C# (Asp.Net Core) )I have the following documentation over a child object of type NameValue.

I wish to have the documentation I added here over FromWarehouse, but when Swagger renders, it uses the definition for NameValue, not FromWarehouse.

/// <summary>
///     The warehouse this transfer is coming from
/// </summary>
/// <remarks>GLW, WDI, PSO, SMA, SHW</remarks>
public NameValue FromWarehouse { get; set; }

Answer 1

You need to do 3 things:

1. The summary should be moved from class property to class.

not here

public NameValue FromWarehouse { get; set; }

but to

/// <summary>
///     The warehouse this transfer is coming from
/// </summary>
/// <remarks>GLW, WDI, PSO, SMA, SHW</remarks>
public class NameValue{
....

2. You need to add document generation, with Include Xml Comments

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

3. Add this to your .csproj file

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

This is the example I used

/// <summary>
///     The warehouse this transfer is coming from
/// </summary>
/// <remarks>GLW, WDI, PSO, SMA, SHW</remarks>
public class NameValue
{
    /// <summary>
    ///     The Name
    /// </summary>
    public string Name { get; set; }
    /// <summary>
    ///     The Value
    /// </summary>
    public string Value { get; set; }
}

Here is the result:

The remarks, I was not able to include the, but as far as I understand, remarks are used to provide payload example, and it is used on top of the resource method.

All this I use with dotnet 6 and Swashbuckle.AspNetCore Version 6.2.3.

I hope it helps.

Reference to Microsoft documentation.