Querystring with ampersand in Swashbuckle xml comments

Question

The docs show this for a POST:

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1"
///     }
/// </remarks>
[HttpPost]
public ActionResult<TodoItem> Create(TodoItem item) { }

But what about a GET:

/// <summary>
/// Gets a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     GET /Todo?iscomplete=true&owner=mike
/// </remarks>
[HttpGet]
public ActionResult<TodoItem> Get(bool isComplete, string owner) { }

The problem is the ampersand in this line: /// GET /Todo?iscomplete=true&owner=mike. The compiler complains: warning CS1570: XML comment has badly formed XML -- 'Expected an end tag for element 'owner'.'

I also tried &.

I actually haven't found an example for GETs.

What is the correct syntax?

Answer 1

For now, we're using a workaround based on EspressoBean's answer but adapted for the ASP.NET Core Swashbuckle library.

In your remarks or summary comments use XML-escaped syntax:

/// <summary>
/// Gets a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     GET /Todo?iscomplete=true&amp;owner=mike
/// </remarks>

In Startup.cs (the ConfigureServices method) add your custom XmlCommentsEscapeFilter:

        services.AddSwaggerGen(c =>
        {
            ...
            c.OperationFilter<XmlCommentsEscapeFilter>();
        });

Add a class called XmlCommentsEscapeFilter.cs:

using Swashbuckle.AspNetCore.Swagger;
using Swashbuckle.AspNetCore.SwaggerGen;

namespace **MyNamespaceHere**
{
    /// <summary>
    /// Replace &amp; with ampersand character in XML comments
    /// </summary>
    internal class XmlCommentsEscapeFilter : IOperationFilter
    {
        public void Apply(Operation operation, OperationFilterContext context)
        {
            operation.Description = operation.Description?.Replace("&amp;", "&");
            operation.Summary = operation.Summary?.Replace("&amp;", "&");
        }
    }
}

For future reference, here's a link to the github issue (still open as of Aug-19-2019): https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1151

Answer 2

I had this same issue and I ended up adding some logic in my document processor as a workaround. I kept the & so that I could search and replace it.

Note: I'm using NSwag which references Swashbuckle libraries, but should be same or close to same code.

In my code comment (note the <remarks> section where I use &) :

    /// <summary>
    /// Get items in cart
    /// </summary> 
    /// <remarks>
    /// api/cart?page=1&amp;size=3
    /// </remarks>

In my Startup.cs (ConfigureServices) I add the use of a Document Processor :

// sets swagger spec object properties        
services.AddOpenApiDocument(s => s.DocumentProcessors.Add(new SwaggerDocumentProcessor())); 

In my Document Processor :

public class SwaggerDocumentProcessor : IDocumentProcessor
{
    public Task ProcessAsync(DocumentProcessorContext context)
    {
        context.Document.Info.Title = "My API Title";
        context.Document.Info.Version = "v1.4";

        foreach (var path in context.Document.Paths)
        {
            foreach (var item in path.Value.Values)
            {
                item.Description = item.Description.Replace("&", "&");
            }
        }

        context.Document.Info.Description = "Description with markdown";
        context.Document.Info.ExtensionData = new ConcurrentDictionary<string, object>();
        context.Document.Info.ExtensionData.Add("x-logo", new
        {
            url =
                "https://www.logos.com/mylogo.jpg",
                altText = "Logo",
            href = "https://website.com/"
        });
        return Task.CompletedTask;
    }
}

In the Document Processor above, note these lines of code:

    foreach (var path in context.Document.Paths)
    {
        foreach (var item in path.Value.Values)
        {
            item.Description = item.Description.Replace("&", "&");
        }
    }

Basically what it's doing is that within the Document.Paths (the url GET, POST, DELETE, etc examples) of the API spec document, it searches and replaces all the & instances with just &.