Swagger/Redoc <remarks> not showing

Question

I am trying to get the XML comments working properly in the docs page, but am having trouble getting the to show. descriptions show just fine, but the remarks are missing completely.

My Swagger config includes c.IncludeXmlComments($@"{AppDomain.CurrentDomain.BaseDirectory}\App_Data\XmlDocument.XML"); and I've confirmed the xml file contains the proper remarks.

All the properties are setup similar to this:

namespace My.Namespace
{
    public class SomeRequestObject
    {
        /// <summary>
        /// Some Property
        /// </summary>
        /// <remarks>
        /// Details about this prop
        /// More details about this prop
        /// </remarks>
        public string SomeProperty { get; set; }
    }
}

I can see the remarks on the method calls themselves, but not on the object properties.

Any ideas on how to get the remarks to show in the UI?

Answer 1

Ok, so I couldn't find a built-in way to do this, but what I ended up doing was creating a custom schema filter and then "manually" added the remarks to the description.

SwaggerConfig.cs:

public class SwaggerConfig
{
    public static void Register()
    {
        GlobalConfiguration.Configuration
            .EnableSwagger(c =>
            {
                // ...Other config options 
                
                c.SchemaFilter<CustomSwaggerSchemaFilter>();
            });
    }
}

Then in the CustomSwaggerFilter.cs file I did:

public class CustomSwaggerSchemaFilter : ISchemaFilter
{
    public void Apply(Schema outputSchema, SchemaRegistry schemaRegistry, Type inputType)
    {
        //Get properties and filter out dupes/empties
        var props = inputType.GetProperties().ToList();
        var baseProps = inputType.BaseType?.GetProperties().ToList();
        if (baseProps != null && baseProps.Any(bp => props.Any(p => p.Name == bp.Name)))
        {
            baseProps.ForEach(bp =>
            {
                var indexToRemove = props.FindIndex(x => x.Name == bp.Name);
                props.RemoveAt(indexToRemove);
                props.Add(bp);
            });
        }

        foreach (var prop in props)
        {
            //Get the remarks in the documentation
            var propType = prop.ReflectedType;
            var remarks = propType.GetDocumentationComment("remarks", 'P', prop.Name);
            var outputProp = outputSchema.properties.FirstOrDefault(x => string.Equals(x.Key, prop.Name, StringComparison.OrdinalIgnoreCase));
            if (outputProp.Value != null && !string.IsNullOrEmpty(remarks))
            {
                //Format remarks to display better
                var formattedRemarks = string.Empty;
                var remarkList = remarks.Split(new char[] { '\r', '\n' }, StringSplitOptions.RemoveEmptyEntries);
                foreach (var remark in remarkList)
                {
                    formattedRemarks += $"  \r\n_{remark.Trim()}_";
                }
                //Append to the description
                outputProp.Value.description += formattedRemarks;
            }
        }
    }
}

Which results in something like this: