Как добавить описание метода в Swagger UI в приложении WebAPI

Question

Я использую Swagger в качестве моей инструментальной среды API, и до сих пор она отлично работает.Я только что наткнулся на эту страницу https://petstore.swagger.io/

и увидел, как у каждого метода есть описание.Например,

POST: pet/ описывается как add a new Pet to the store.Я думал, что добавление что-то вроде [Description("Description text")] должно сделать это, но это не так.Как мне этого добиться?

Answer 1

Это хорошо задокументировано в проекте: https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments

---

Включить описания из комментариев XML

Чтобы улучшить сгенерированные документы с понятными для человека описаниями, вы можете комментировать действия контроллераи модели с XML-комментариями и настройкой Swashbuckle для включения этих комментариев в выводимый Swagger JSON:

1 - откройте диалоговое окно «Свойства» для своего проекта, нажмите вкладку «Построить» и убедитесь, что «Файл документации XML "проверен.Это создаст файл, содержащий все комментарии XML во время сборки.

На этом этапе любые классы или методы, НЕ аннотированные комментариями XML, вызовут предупреждение о сборке.Чтобы подавить это, введите код предупреждения «1591» в поле «Подавить предупреждения» в диалоговом окне свойств.

2 - Настройте Swashbuckle для включения XML-комментариев к файлу в сгенерированный Swagger JSON:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1",
        new Info
        {
            Title = "My API - V1",
            Version = "v1"
        }
     );

     var filePath = Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml");
     c.IncludeXmlComments(filePath);
}

3 - аннотируйте свои действия с помощью сводки, замечаний и тегов ответов:

/// <summary>
/// Retrieves a specific product by unique id
/// </summary>
/// <remarks>Awesomeness!</remarks>
/// <response code="200">Product created</response>
/// <response code="400">Product has missing/invalid values</response>
/// <response code="500">Oops! Can't create your product right now</response>
[HttpGet("{id}")]
[ProducesResponseType(typeof(Product), 200)]
[ProducesResponseType(typeof(IDictionary<string, string>), 400)]
[ProducesResponseType(500)]
public Product GetById(int id)

4 - вы также можете аннотировать типы с помощью тегов сводки и примеров:

public class Product
{
    /// <summary>
    /// The name of the product
    /// </summary>
    /// <example>Men's basketball shoes</example>
    public string Name { get; set; }

    /// <summary>
    /// Quantity left in stock
    /// </summary>
    /// <example>10</example>
    public int AvailableStock { get; set; }
}

5 - Перестройте проект, чтобы обновить файл комментариев XML и перейти к конечной точке Swagger JSON.Обратите внимание, как описания сопоставляются с соответствующими полями Swagger.

ПРИМЕЧАНИЕ. Вы также можете предоставить описания схемы Swagger, добавив аннотации к своим моделям API и их свойствам с помощью сводных тегов.Если у вас есть несколько файлов комментариев XML (например, отдельные библиотеки для контроллеров и моделей), вы можете вызывать метод IncludeXmlComments несколько раз, и все они будут объединены в выходной Swagger JSON.

---

FollowВ инструкции внимательно вы должны получить что-то похожее на:
https://swashbucklenetcore.azurewebsites.net/swagger/

Answer 2

Мы используем дополнительные атрибуты, чтобы добавить необходимые детали в документацию по чванству:

    [SwaggerOperationSummary("Add a new Pet to the store")]
    [SwaggerImplementationNotes("Adds a new pet using the properties supplied, returns a GUID reference for the pet created.")]
    [Route("pets")]
    [HttpPost]
    public async Task<IHttpActionResult> Post()
    {
        ...
    }

И затем в вашем чванстве обязательно примените следующие фильтры:

config.EnableSwagger("swagger",
           c =>
           {
               c.OperationFilter<ApplySwaggerImplementationNotesFilterAttributes>();
               c.OperationFilter<ApplySwaggerOperationSummaryFilterAttributes>();

Код дляфильтры:

public class ApplySwaggerImplementationNotesFilterAttributes : IOperationFilter
{
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
    {
        var attr = apiDescription.GetControllerAndActionAttributes<SwaggerImplementationNotesAttribute>().FirstOrDefault();
        if (attr != null)
        {
            operation.description = attr.ImplementationNotes;
        }
    }
}

public class ApplySwaggerOperationSummaryFilterAttributes : IOperationFilter
{
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
    {
        var attr = apiDescription.GetControllerAndActionAttributes<SwaggerOperationSummaryAttribute>().FirstOrDefault();
        if (attr != null)
        {
            operation.summary = attr.OperationSummary;
        }
    }
}

Answer 3

Вы можете использовать комментарий для документации (3 слеша вместо стандартных 2), например:

/// <summary>
/// This is method summary I want displayed
/// </summary>
/// <param name="guid">guid as parameter</param>
/// <param name="page_number">Page number - defaults to 0</param>
/// <returns>List of objects returned</returns>