Swagger/Redoc 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?

Dryden, were you able to figure this out? I'm running into the same issue. In older versions of swashbuckle i've seen the pull in to the swagger file but it's no longer doing this on newer versions. — James, Nov 09 '22 at 00:01
@James Probably a little late, but I posted an answer below on how I achieved getting the remarks to show. Slightly hacky, but works just fine for my purposes. — Dryden Long, Dec 21 '22 at 22:41

score 1 · Answer 1 · answered Dec 21 '22 at 22:41

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:

Swagger/Redoc not showing

1 Answers1