Question 86032 in ASP.NET Question posted in
The official documentation can be found here.

How to handle <see /> XML documentation tags in Swagger? – Asp.net

I have an ASP.Net Web API with XML documentation throughout, including many <see /> tags.

I’ve recently added Swagger (Swashbuckle UI stuff) to the solution, and noticed that it doesn’t handle XML tags like <see />. After looking around online I found this – https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/57, so it seems like the devs don’t want to fix this.

Does anybody have any suggestions? I tried running a little .exe to replace all tags in the generated XML file with their object names (e.g. <see cref="MyObject"/> becomes MyObject), but this kept screwing up and even when I did it manually Swagger for some reason didn’t pick up the changes (is the XML loaded into memory somewhere?)

Tags:

2

Answers


  1. Chosen as BEST ANSWER
    0

    Following on from Kit's suggestion, I found a way to retrieve and change the documentation, but needed a way to parse XML tags. I found this which, although it refers to HTML, removes XML tags just as well.

    So, in the order they are required:

    1. I have a common Utilities class where I put the above HtmlAgilityPack code (though I called the method RemoveXMLTags)
    2. Added a new XmlDocumentFilter class as below:
    public class XmlDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        foreach (var path in swaggerDoc.Paths)
        {
            foreach (var operation in path.Value.Operations)
            {
                operation.Value.Description = Utilities.RemoveXMLTags(operation.Value.Description);

                operation.Value.Summary = Utilities.RemoveXMLTags(operation.Value.Summary);

                if (operation.Value.RequestBody != null)
                {
                    operation.Value.RequestBody.Description = Utilities.RemoveXMLTags(operation.Value.RequestBody.Description);
                }

                foreach (var parameter in operation.Value.Parameters)
                {
                    parameter.Description = Utilities.RemoveXMLTags(parameter.Description);
                }
            }
        }
    }
}
    1. Added the following to my Startup class:
    services.AddSwaggerGen(setupAction =>
    {
        setupAction.SwaggerDoc(
            "MyAppAPIDocumentation",
            new OpenApiInfo() { Title = "MyApp API", Version = "1" });

        var xmlDocumentationFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlDocumentationFullPath = Path.Combine(AppContext.BaseDirectory, xmlDocumentationFile);

        setupAction.IncludeXmlComments(xmlDocumentationFullPath);
        setupAction.DocumentFilter<XmlDocumentFilter>();
    });
    1. Profit

  2. 0

    XML documentation comments are generated into a file with the same name as the assembly in the same folder (usually). You could parse that file with the XDocument and related classes, and then use a schema filter (ISchemaFilter) to set the appropriate properties on the Open API schema that Swashbuckle exposes.

    I’m unsure of what schema element would be appropriate for a "see also" or "related resources" functionality. You would need to investigate that (perhaps a custom property in ASP.NET Core’s Open API implementation, or by appending text to a description property).

    As to

    is the XML loaded into memory somewhere?

    Yes. Swashbuckle itself parses this XML to do all that it currently does. Roughly speaking it builds it into a document object model (DOM) built on top of Microsoft’s Open API implementation mentioned above. Using a schema filter will give you access to that DOM.

    Login or Signup to reply.
Please signup or login to give your own answer.

Back To Top
Search