Строка запроса с амперсандом в комментариях Swashbuckle xml - PullRequest
Новая
       20

Строка запроса с амперсандом в комментариях Swashbuckle xml

2 голосов
/ 09 мая 2019

Документы показывают это для 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'.'

Я тоже пытался &amp;.

На самом деле я не нашел пример для GET.

Какой правильный синтаксис?

1 Ответ

1 голос
/ 06 июня 2019

У меня была такая же проблема, и я решил добавить некоторую логику в процессор документов в качестве обходного пути. Я сохранил &amp;, чтобы найти и заменить его.

Примечание: я использую NSwag, который ссылается на библиотеки Swashbuckle, но должен быть одинаковым или близким к тому же коду.

В моем кодовом комментарии ( обратите внимание на раздел <remarks>, в котором я использую &amp;) : 

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

По сути, он выполняет то, что в Document.Paths (примеры URL GET, POST, DELETE и т. Д.) Документа спецификации API он ищет и заменяет все экземпляры &amp; всего на &.

...