В чём разница между описанием API и генерацией кода из Swagger?

Question

Описание API — это спецификация: список эндпоинтов, схем данных, параметров и ответов. Генерация кода — это автоматическое создание клиента или серверных заготовок по этой спецификации. Описание нужно всем участникам, даже если код никто не генерирует. Генерация полезна, чтобы быстрее стартовать и снизить количество ручных ошибок. Но она не заменяет осмысленное проектирование API.

YeaHub · Accepted Answer

Описания API и генерация кода решают разные задачи: первое фиксирует договорённость, второе помогает использовать эту договорённость в коде.ОпределениеОписание API (OpenAPI spec) — формальное описание контракта между клиентом и сервером: какие методы существуют, какие параметры принимаются, какие ответы возвращаются и в каком формате.Генерация кода — применение этого описания для автоматического создания программных артефактов: SDK-клиента, моделей данных, серверных заглушек, документации.Что даёт описание API (и почему оно нужно само по себе)1) Единый контракт и «язык общения»Описание API полезно даже без генерации: оно позволяет обсуждать изменения, проектировать интеграции и понимать границы ответственности.Кому помогаетbackend: фиксирует, что именно обещает серверfrontend/mobile: понимают, что и как можно вызватьQA: знают ожидаемые ответы и ошибкиГлавная ценностьдоговорённость становится явной и проверяемой2) Документация и тестированиеSwagger UI строится из спецификации и даёт удобную «витрину» API.Пример пользыбыстро увидеть параметры и форматывоспроизвести запрос и посмотреть ответВажное ограничениеесли спека не обновляется, документация начинает вратьЧто даёт генерация кода (и какие тут нюансы)1) Генерация клиента (SDK)Генерация клиента превращает «строки URL и JSON» в типизированные вызовы методов.Плюсыменьше ручного HTTP-кодаменьше ошибок при сборке запросовмодели и методы согласованы со спецификациейМинусыможет появиться «тяжёлый» клиент и сложные обновленияиногда код неудобен, и его всё равно оборачивают своим адаптером2) Генерация серверных заготовокМожно сгенерировать контроллеры-скелеты и модели, чтобы быстрее стартовать.Когда это полезнопрототипыбыстрый старт нового сервисастрогое следование контракту (contract-first)Когда осторожнееесли бизнес-логика сложная, «скелет» мало помогаетесли API активно развивается, частая перегенерация мешает3) Contract-first vs code-firstContract-firstсначала пишем OpenAPI, потом реализуемудобно для межкомандных контрактовCode-firstсначала пишем код контроллеров, потом генерируем спекубыстрее для небольших команд и внутренних сервисовМини-пример: что именно можно генерироватьКлиентские методыgetUser(id) вместо GET /users/{id} строкойМодели данныхUserDto как тип, а не «карта полей»Заготовки эндпоинтов на сервереметоды контроллеров без реализации// Идея: генератор создал интерфейс клиента
interface UsersApi {
    UserDto getUser(long id);
    // ... другие методы
}
Краткий выводОписание API — это контракт, который нужен сам по себе для согласования и понимания интеграций. Генерация кода — полезная автоматизация поверх этого контракта: ускоряет разработку и снижает ручные ошибки, но требует дисциплины при обновлениях и не заменяет проектирование API.