Что такое Swagger (OpenAPI) в контексте ASP.NET Core?

Так, слушай сюда, про этот ваш Swagger, он же теперь OpenAPI. Это не просто какая-то хуйня для галочки, а реально полезная штука, которая тебе жизнь облегчит. В мире .NET, когда говорят "поставь Swagger", обычно имеют в виду Swashbuckle — библиотеку, которая из твоего кода на ASP.NET Core сама, блядь, генерирует документацию и веб-морду для тестирования API.

Ну и нахуя это надо?

1. Документация сама себя пишет. Не нужно отдельно в Confluence или ещё в какую-то жопу вести changelog. Изменил контроллер — документация обновилась автоматом. Волшебство, ёпта.
2. Интерактивная веб-хата (Swagger UI). Ты получаешь страничку, где видишь все свои эндпоинты, какие данные они жрут и что отдают. И самое главное — можно прямо там, не выходя из браузера, тыкать кнопочки и дергать свой же API. Для тестирования — просто пиздец как удобно.
3. Стандарт, блядь. На выходе получается JSON файл по спецификации OpenAPI. Его потом можно запихнуть куда угодно: в Postman импортировать, клиентский код сгенерить или на API-гейтвей закинуть.

Как впилить это дело в ASP.NET Core 6 и новее:

Смотри, делается всё просто, как три копейки. Открываешь Program.cs и пишешь:

using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// 1. Вот эти две строчки добавляют возможность Swagger'у ковыряться в твоём коде
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Моё API для товаров",
        Version = "v1",
        Description = "Тут можно товары создавать, удалять и вообще всё, что душе угодно",
        Contact = new OpenApiContact { Name = "Наша команда", Email = "dev@example.com" }
    });
    // Если у тебя есть JWT авторизация, можно и её добавить, чтобы в UI токен прокидывать
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Description = "Вот сюда пиши 'Bearer {твой_токен}'",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,
        Scheme = "Bearer"
    });
});

var app = builder.Build();

// 2. А вот это подключает сам Swagger в пайплайн (обычно только для разработки)
if (app.Environment.IsDevelopment())
{
    app.UseSwagger(); // Эта штука генерит JSON по адресу /swagger/v1/swagger.json
    app.UseSwaggerUI(c => // А эта — отдаёт красивую веб-страницу по адресу /swagger
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Моё API V1");
        // c.RoutePrefix = string.Empty; // Если хочешь, чтобы эта страница открывалась сразу на корне сайта
    });
}

app.MapControllers();
app.Run();

Как сделать документацию ещё понятнее?

Можно контроллеры и методы разукрасить атрибутами и комментариями, чтобы в Swagger UI было вообще красота.

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class ProductsController : ControllerBase
{
    /// <summary>
    /// Достаёт товар из базы по айдишнику.
    /// </summary>
    /// <param name="id">Айди товара, целое число.</param>
    /// <returns>Найденный товар или 404, если такого нет.</returns>
    /// <response code="200">Вот он, товар, любуйся.</response>
    /// <response code="404">А вот и хуй — товара нет.</response>
    [HttpGet("{id}")]
    [ProducesResponseType(typeof(Product), StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public IActionResult GetById(int id)
    {
        // ... тут твоя логика
        return Ok(new Product { Id = id, Name = "Пример" });
    }

    [HttpPost]
    [Consumes("application/json")]
    [ProducesResponseType(typeof(Product), StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public IActionResult Create([FromBody] CreateProductDto dto)
    {
        // ... логика создания
        return CreatedAtAction(nameof(GetById), new { id = 1 }, dto);
    }
}

После этого запускаешь приложение и просто открываешь в браузере https://localhost:xxxx/swagger. И всё, блядь! Видишь всю свою API-роспись, можешь по каждому методу нажать Try it out и отправить запрос. Удобство — просто овердохуища.

Короче, вывод

Swashbuckle (Swagger) — это не прихоть, а must-have для любого адекватного API на .NET. Он экономит кучу времени на общении с фронтендерами, на тестировании и избавляет от головной боли с ведением документации. Бери и используй, не мудри.