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

Я использую атрибуты SwaggerResponse, чтобы украсить мои действия контроллера api, все это прекрасно работает, однако, когда я смотрю на сгенерированную документацию, поле описания для параметров пуст.

Существует ли подход, основанный на атрибутах, для описания параметров действия (а не комментариев XML)?

Ответы

Ответ 1

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

Для этого требуются следующие условия:

XML-комментарии должны быть включены и настроены с помощью Swagger
Параметры должны быть явно украшены либо [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);
}

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

Ответ 2

Вы должны подтвердить, что вы разрешаете 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 >

Ответ 3

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

Затем следуйте вашему методу 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);
    }
});