Описание параметров Swashbuckle

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

Он требует соблюдения следующих условий:

• комментарии XML должны быть включены и настроены с помощью Чванство
• Параметры должны быть явно украшены либо [FromRoute], [FromQuery], [FromBody], либо [FromUri].
• То же самое для типа метода (get/post/put и т. д.), который должен быть украшен [Http...]
• Опишите параметр, как обычно, с помощью комментария <param ...> xml.

Полный образец выглядит так:

/// <summary>
/// Short, descriptive title of the operation
/// </summary>
/// <remarks>
/// More elaborate description
/// </remarks>
/// <param name="id">Here is the description for ID.</param>
[ProducesResponseType(typeof(Bar), (int)HttpStatusCode.OK)]
[HttpGet, Route("{id}", Name = "GetFoo")]
public async Task<IActionResult> Foo([FromRoute] long id)
{
    var response = new Bar();
    return Ok(response);
}

Что производит следующий вывод:

Вы должны подтвердить, что разрешаете Swagger использовать XML-комментарии.

httpConfig.EnableSwagger(c => {
                if (GetXmlCommentsPath() != null) {
                    c.IncludeXmlComments(GetXmlCommentsPath());
                }
...
...
);

protected static string GetXmlCommentsPath() {
    var path = HostingEnvironment.MapPath("path to your xml doc file");
    return path;
}

Вам также следует убедиться, что вы создаете XML-документ для желаемого проекта. В нужном вам проекте Свойства (Alt + Enter в верхней части проекта или щелкните правой кнопкой мыши -> Свойства) -> Создать -> Проверить Файл документации XML

Для полноты картины при использовании последней версии Swashbuckle.AspNetCore (2.1.0) и Swashbuckle.SwaggerGen/Ui (6.0.0) включите генерацию файла документации Xml в сборке вашего проекта.

Затем следующее к вашему методу ConfigureServices():

services.ConfigureSwaggerGen(options =>
{
    options.SingleApiVersion(new Info
    {
        Version = "v1",
        Title = "My API",
        Description = "API Description"
    });
    options.DescribeAllEnumsAsStrings();

    var xmlDocFile = Path.Combine(AppContext.BaseDirectory, $"{_hostingEnv.ApplicationName}.xml");
    if (File.Exists(xmlDocFile))
    {
        var comments = new XPathDocument(xmlDocFile);
        options.OperationFilter<XmlCommentsOperationFilter>(comments);
        options.ModelFilter<XmlCommentsModelFilter>(comments);
    }
});