OpenAPI specs maintenance

OpenAPI specs maintenance — это создание и поддержание в актуальности OpenAPI-спецификации вашего API: формального, машиночитаемого описания всех методов, параметров, ответов и ошибок. Спецификация — это источник правды для всего вокруг API: из неё генерируются документация (см. «Документация для разработчиков»), клиентские SDK (см. «SDK generation»), интерактивный playground (см. «API playgrounds») и коллекции Postman (см. «Postman collections maintenance»). Поэтому её качество определяет качество всего остального: точная спека — и доки, и SDK, и песочница строятся из неё уже правильными; неточная — тиражирует ту же ошибку во все артефакты разом. Оговоримся честно: автоматическая генерация переносит в артефакты ровно то, что есть в спеке, — она не чинит саму спеку за вас, поэтому качество всего по-прежнему равно качеству спеки и процесса её ведения. Приводим вашу спецификацию в порядок (или создаём с нуля по реальному API), доводим до стандарта OpenAPI 3.x, настраиваем линтинг и проверки, а главное — связываем с кодом, чтобы спека не расходилась с реальностью: контрактные тесты и проверки в CI ловят расхождения до того, как их увидит интегратор. Важно честно: ценность спецификации — в том, что она совпадает с настоящим API. Спека, которая разошлась с кодом, опаснее её отсутствия: она уверенно врёт всем, кто на неё опирается, и тащит ошибку в доки, SDK и тесты разом. Поэтому одноразово «написать спеку» мало — нужен процесс, который держит её честной; его мы и ставим. Ещё честно про объём: если у вас нет потребителей API и он внутренний и простой, полноценная поддерживаемая спецификация может быть избыточна — но как только вы планируете документацию, SDK или внешних интеграторов, спека становится фундаментом, без которого остальное строить дорого и криво. Скажем прямо, нужна ли она вам уже сейчас. Представьте: разработчик меняет метод, CI сразу проверяет спецификацию на соответствие, и доки, SDK и playground обновляются из одного источника — без ручной синхронизации десяти мест. Базовая цена — от 50 000 ₽ за приведение в порядок; миграция со старого формата (Swagger 2.0) или давно заброшенной спеки, а также поддержка и интеграция в CI считаются отдельно.

• Описание API живёт в головах и устаревших документах — единого источника нет.
• Документация, SDK и тесты расходятся между собой — каждый правят руками.
• Спецификация есть, но не совпадает с реальным API — ей нельзя доверять.
• Любое изменение API приходится вручную разносить по доке, SDK, Postman и тестам.

• Создание или приведение в порядок OpenAPI-спецификации (3.x)
• Полное описание методов, параметров, ответов, ошибок, авторизации
• Линтинг и проверки качества спецификации (единый стиль, полнота)
• Связь с кодом: контрактные тесты, проверки соответствия
• Проверки в CI, чтобы спека не расходилась с API
• Версионирование спецификации
• Единый источник для документации, SDK, playground, Postman
• Правила и процесс поддержания в актуальности

• Один источник правды — всё про API в одном формальном описании
• Доки, SDK, playground и Postman строятся и обновляются из спеки
• Спецификация совпадает с реальным API — ей снова доверяют
• Изменение API не нужно вручную разносить по десяти местам

• Смотрим реальный API и текущее описание, оцениваем расхождения
• Приводим спецификацию к стандарту, настраиваем линтинг и контрактные тесты
• Встраиваем проверки в CI, версионируем, передаём процесс

• Зачем отдельная спецификация — у нас же есть документация?

  Документация и спецификация — это разные слои. Спецификация (OpenAPI) — формальное машиночитаемое описание, источник, из которого документация, SDK, playground и Postman генерируются автоматически. Если поддерживать только документацию руками, она быстро разойдётся с SDK и тестами, потому что у них нет общего источника. Спека и есть этот общий источник: правите её — и всё остальное обновляется согласованно.

• А спецификация не разойдётся с кодом, как часто бывает?

  Это главный риск, и именно его мы решаем. Разовая спека действительно быстро устаревает. Поэтому мы связываем её с кодом: контрактные тесты и проверки в CI ловят расхождение между спекой и реальным API на этапе разработки, а не когда об этом напишет рассерженный интегратор. Полностью исключить дрейф нельзя, но сделать так, чтобы он не проходил молча, — реально. Что именно ловят такие проверки: несовпадение методов и полей, кодов ответов, форматов и обязательности параметров, пропавшие или лишние эндпоинты. Чего они не увидят — смысл и бизнес-логику: что метод формально соответствует спеке, но делает не то, проверяет уже человек.

• Нам точно нужна поддерживаемая спецификация?

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