Swashbuckle xml 评论中带有 & 符号的查询字符串

Question

The docs 显示此 POST:

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

但是 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) { }

问题出在这一行中的 & 符号：/// GET /Todo?iscomplete=true&owner=mike。编译器抱怨：warning CS1570: XML comment has badly formed XML -- 'Expected an end tag for element 'owner'.'

我也试过&.

实际上我还没有找到 GET 的例子。

正确的语法是什么？

Answer 1

我遇到了同样的问题，最后我在我的文档处理器中添加了一些逻辑作为解决方法。我保留了 & 以便我可以搜索和替换它。

注意：我正在使用 NSwag，它引用了 Swashbuckle 库，但应该是相同或接近相同的代码。

在我的代码注释中（注意我使用 & 的 <remarks> 部分）:

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

在我的 Startup.cs (ConfigureServices) 中我添加了文档处理器的使用 :

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

在我的文档处理器中：

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("&amp;", "&");
            }
        }

        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;
    }
}

在上面的文档处理器中，注意以下代码行：

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

基本上它所做的是在 API 规范文档的 Document.Paths（url GET、POST、DELETE 等示例）中，它搜索并用 &.

替换所有 & 实例

Answer 2

目前，我们正在使用基于 EspressoBean 的答案但适用于 ASP.NET Core Swashbuckle 库的解决方法。

在您的备注或摘要评论中使用 XML-转义语法：

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

在 Startup.cs（ConfigureServices 方法）中添加您的自定义 XmlCommentsEscapeFilter：

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

添加一个名为class的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;", "&");
        }
    }
}

为了将来参考，这是 github 问题的 link（截至 2019 年 8 月 19 日仍然开放）：https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1151

Swashbuckle xml 评论中带有 & 符号的查询字符串

Querystring with ampersand in Swashbuckle xml comments

c#

swagger

swashbuckle