Developer

OpenAPI и Swagger, версионирование API

↑ 3.3 Web API: контроллеры, Minimal API, валидация · ← Предыдущая · → Следующая

Обязательно~3 мин чтенияУровень: middle

Зачем это на собесе

Про контракт и эволюцию API: как документировать и как вносить ломающие изменения.

Объяснение

OpenAPI — спецификация описания HTTP API; Swagger UI — интерфейс для просмотра/вызова. В .NET 9 встроенная генерация Microsoft.AspNetCore.OpenApi заменила Swashbuckle по умолчанию.

builder.Services.AddOpenApi();
app.MapOpenApi();                  // /openapi/v1.json
// UI: Scalar или Swagger UI поверх json
orders.MapGet("{id:guid}", Get)
      .WithName("GetOrder")
      .WithSummary("Получить заказ")
      .Produces<OrderDto>()
      .ProducesProblem(404);

Версионирование

СпособПримерЗамечание
URL/v2/ordersсамый простой, видно в логах
ЗаголовокX-Api-Version: 2чище URL, сложнее тестировать
Media typeapplication/vnd.app.v2+json«строгий REST»
Query?api-version=2.0стандарт Asp.Versioning
builder.Services.AddApiVersioning(o => { o.DefaultApiVersion = new(1, 0); o.ReportApiVersions = true; })
    .AddApiExplorer();

Ломающие и безопасные изменения

БезопасноЛомающее
новое необязательное поле в ответеудаление/переименование поля
новый endpointсмена типа поля, обязательности
новое значение enum с толерантным клиентомсмена семантики кода ответа

Политика: объявить deprecation (заголовки Deprecation/Sunset), поддерживать N версий, тестировать контрактами.

Нюансы и подводные камни

  • Генерация клиента из OpenAPI (NSwag, Kiota) ускоряет интеграции, но требует точной схемы (Produces).
  • Не публикуйте Swagger на проде без необходимости или защитите его.
  • Не смешивайте версии в одной модели: копируйте DTO по версиям.
  • Схема без описания ошибок вводит потребителей в заблуждение.

Практика

  1. Подключите AddOpenApi и Scalar, добавьте описания и примеры.
  2. Реализуйте v1 и v2 одного endpoint и заголовки deprecation.
  3. Сгенерируйте типизированный клиент из схемы.

Вопросы с ответами

Связанные темы

Вид графа

Обратные ссылки