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等示例）内，它搜索并仅用{{替换所有&实例1}}。

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

添加一个名为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问题的链接（截至2019年8月19日仍开放）：https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1151

Swashbuckle xml注释中带有＆符的查询字符串

2 个答案: