{"canonical_url":"https://engineer.company/uk/glossary/openapi/","content_markdown":"# OpenAPI\n\n## Що це таке\n\nOpenAPI — це стандартний формат, у якому в одному файлі JSON або YAML записують усе, що треба\nзнати тому, хто викликає HTTP API: адреси, операції, вхідні й вихідні дані, помилки та безпеку, —\nі цей файл однаково читають люди й програми. Сам стандарт має назву OpenAPI Specification,\nскорочено OAS, а файл, написаний за ним, називають описом OpenAPI. Формат починався як Swagger\nSpecification, і стара назва досі живе в інструментах, побудованих навколо нього, як-от Swagger\nUI.\n\nСпецифікація називає себе незалежним від мови програмування описом інтерфейсу для HTTP API. Мета,\nяку вона ставить, — щоб людина чи програма могла зрозуміти, що робить сервіс, не маючи ні його\nвихідного коду, ні додаткової документації, ні запису мережевого трафіку. Головний документ\nрекомендовано називати `openapi.json` або `openapi.yaml`, а великі описи часто ділять на кілька\nфайлів, пов'язаних посиланнями.\n\nІсторія формату проходить через одну передачу. Swagger 2.0 вийшов у вересні 2014 року, а 31 грудня\n2015 року його передали OpenAPI Initiative. Версія 3.0.0 з'явилася в липні 2017 року вже під новою\nназвою, 3.1.0 — у лютому 2021-го, а 3.2.0 — у вересні 2025-го.\n\nОпис має кілька частин верхнього рівня. `info` називає API та його версію; `servers` перелічує, де\nвін працює; `paths` містить кожну адресу, а під нею — по одній операції на кожен метод HTTP з її\nпараметрами, тілом запиту й можливими відповідями. `components` збирає те, що використовують\nповторно: схеми даних, параметри, відповіді та схеми безпеки, які описують, як автентифікується\nтой, хто викликає. Від версії 3.1 розділ `webhooks` може описувати ще й запити, які API сам\nнадсилає своїм споживачам. Мінімальний фрагмент:\n\n```yaml\nopenapi: 3.1.0\ninfo:\n    title: Orders\n    version: 1.4.0\npaths:\n    /orders/{id}:\n        get:\n            operationId: getOrder\n            parameters:\n                - name: id\n                  in: path\n                  required: true\n                  schema:\n                      type: string\n            responses:\n                \"200\":\n                    description: One order\n```\n\nСтруктури даних задають окремою мовою. Від 3.1 Schema Object є надмножиною JSON Schema Draft\n2020-12; 3.0 використовувала розширену підмножину старішої чернетки з власними доповненнями. JSON\nSchema описує один фрагмент даних, а OpenAPI — цілий HTTP API і для окремих фрагментів позичає JSON\nSchema. Сусіди описують інші види інтерфейсів: AsyncAPI охоплює системи, побудовані на обміні\nповідомленнями, сервіси gRPC оголошують у файлах `.proto` формату [Protocol Buffers](https://protobuf.dev/), а сервер GraphQL\nпублікує опис власних типів.\n\n## Чому це важливо\n\nОпис у стандартному форматі — це один файл, який читає багато інструментів, і кожен із них\nзаощаджує роботу, яку команда інакше робила б уручну. З нього рендерять довідкову документацію. З\nнього генерують клієнтські бібліотеки кількома мовами, тож фронтенд викликає типізовану функцію, а\nне складає URL сам. Мок-сервери відповідають на запити на його основі, тож фронтенд можна будувати\nще до появи бекенду. Шлюзи імпортують із нього маршрути, тести звіряють із ним трафік, а\nШІ-агенти, які викликають API, читають його, щоб дізнатися, що їм пропонують.\n\nЦе охоплення водночас і ризик. Кожен із цих інструментів довіряє файлу. Хибний опис гірший за\nвідсутній, бо згенерований клієнт компілюється, документація має авторитетний вигляд, а помилка\nвиявляється вже під час роботи, у чужому продукті.\n\nТож головне рішення — звідки береться опис. У підході design-first люди пишуть опис, рецензують\nйого як контракт і лише тоді будують сервер відповідно до нього. Форму API обговорюють ще до появи\nкоду, що пасує публічним API і командам, які працюють паралельно. Ціна в тому, що опис і сервер —\nдві окремі речі, які можуть розійтися. У підході code-first опис генерують із власних типів і\nанотацій сервера. Він не може описати маршрут, якого сервер не має, але точний лише настільки,\nнаскільки точні ці типи, а обговорення дизайну відбувається в code review, а не в документі. Хоч\nби який шлях обрали, опис лишається правдивим, тільки якщо його перевіряє збірка.\n\nВерсії важать більше, ніж здається. Перехід із 3.0 на 3.1 змінив спосіб опису структур даних, бо 3.1\nперейняла JSON Schema 2020-12. Генератори, валідатори й шлюзи підтримують кожен свій діапазон\nверсій, тож версію, якою пише команда, обмежує найстаріший інструмент у ланцюжку.\n\n## Як це виглядає на практиці\n\nAPI однієї платформи починався на Fiber із валідацією, написаною вручну для кожного ендпоінта,\nі без єдиного документа, що описував би його форму.\n[HTTP-рівень перейшов на Huma v2](/uk/portfolio/migrated-the-api-to-huma-v2-at-100-parity/)\nповерх Fiber, тож кожен ендпоінт оголошують через вхідні й вихідні структури, а опис OpenAPI\nгенерується з цих типів; документація встигає за кодом, а не старіє у вікі. Два ендпоінти\nWebSocket лишилися на чистому Fiber, поза моделлю запиту й відповіді, яку пропонує Huma. Сторінка\nпрямо пояснює, чому важить масштаб: коли операцій 760, а шляхів 649, опис стає по суті єдиним\nспособом прочитати API, тож упевненість у його повноті важить більше, ніж тоді, коли їх було\nп'ятдесят. Перевірка в CI тримає відповідність між маршрутами й описом на рівні 100%.\n\nНа іншій платформі опис — середня ланка ланцюга, що тягнеться від бази даних назовні. Схема та її\nфункції задають типи Go,\n[Huma видає опис, а з нього генерують усе, чим користується фронтенд](/uk/portfolio/generated-the-api-contract-from-the-database-out/):\nтипізований клієнт TypeScript на 44 076 рядків, 61 мок-обробник для тестів фронтенду та обмеження,\nякі застосовує кожна форма. Так долають розходження між фронтендом і бекендом, яке зазвичай\nдається взнаки як 422 у браузері, коли розбіжність уже потрапила в реліз. Перевірка контракту в CI\nзупиняє збірку в разі розбіжності й окремо прискіпливо звіряє необов'язкові поля тіла запиту, де\nплутають «відсутнє» і null, та enum-и параметрів запиту. Ціну сторінка теж називає: крок генерації\nпосеред усього й ланцюг, якому можна довіряти лише настільки, наскільки надійна його найслабше\nзахищена ланка.\n\n[Сторінка компанії про готовність до ШІ-агентів](/uk/ai-ready/) застосовує ту саму логіку до\nагентів. Застосунок, яким можуть користуватися агенти, пропонує описаний API: документ OpenAPI,\nMCP-сервер там, де агентам слід викликати застосунок напряму, і метадані OAuth, щоб агент міг\nдіяти від імені користувача і ніхто не передавав свого пароля. Кожну рекомендацію для агентів\nсторінка класифікує, а не виконує наосліп, і оскільки власний сайт компанії не має API, каталог\nAPI та метадані OAuth — дві з п'яти, від яких там відмовилися.\n\n## Де виникають проблеми\n\n**Опис обіцяє те, чого сервер не робить.** Опис, який підтримують уручну, відстає: новий параметр\nзапиту, перейменоване поле чи код помилки, про який знає лише сервер. Згенеровані клієнти тоді\nкомпілюються на основі вигаданого опису. Генеруйте опис із коду або тримайте його окремо й перевіряйте за ним\nсправжні запити та відповіді в тестах, а також порівнюйте маршрути, які реєструє сервер, зі\nшляхами, які перелічує опис.\n\n**Кожна перегенерація клієнта перейменовує половину методів.** Без `operationId` генератори\nвигадують назви методів зі шляху та методу HTTP, тож перенесення маршруту перейменовує функцію,\nяку викликає кожен клієнт. Специфікація вимагає, щоб кожен `operationId` був унікальним, і\nрозрізняє в ньому великі й малі літери. Задайте його кожній операції, добирайте так само ретельно,\nяк назву публічної функції, і нехай лінтер зупиняє збірку, коли його бракує.\n\n**Поля, що можуть бути null, після оновлення починають відхиляти null.** OpenAPI 3.0 позначала їх\nяк `nullable: true`. У 3.1 цього ключового слова вже немає, тип стає списком, а валідатор, що\nнатрапляє на незнайоме ключове слово, зазвичай його пропускає. Схема 3.0, якій просто змінили\nномер на 3.1, тому відхиляє null усюди, де автор хотів його дозволити. Перетворюйте схеми за\nпосібником OpenAPI Initiative з оновлення, де описано й те, що `exclusiveMinimum` стає числом:\n\n```yaml\n# OpenAPI 3.0\ntype: string\nnullable: true\n---\n# OpenAPI 3.1\ntype: [string, \"null\"]\n```\n\n**Приклади не проходять власну схему.** Специфікація каже, що приклад слід узгоджувати з його\nсхемою, а перевірку залишає інструментам. Читач копіює приклад із документації й отримує 422;\nмок-сервер віддає його, і фронтенд будують на даних, які справжній API відхилить. Перевіряйте\nкожен приклад у CI так само суворо, як живий трафік.\n\n**Публічний опис відкриває карту адміністративного API.** Один опис, згенерований з усіх маршрутів\nі доступний за публічною адресою, показує внутрішні операції та їхні схеми кожному, хто запитає.\nПублікуйте окремий опис для кожної аудиторії, згенерований без внутрішніх операцій. Специфікація\nдозволяє залишати об'єкти порожніми або прибирати їх саме для такого контролю доступу.\n\n## Що почитати далі\n\n- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) — остання версія стандарту з\n  визначенням кожного об'єкта й поля та історією кожного випуску.\n- [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12) — мова схем, якою OpenAPI 3.1\n  і новіші версії описують тіло кожного запиту й відповіді.\n- [Upgrading from OpenAPI 3.0 to 3.1](https://learn.openapis.org/upgrading/v3.0-to-v3.1.html) —\n  власний перелік змін у схемах від OpenAPI Initiative, серед них і `nullable`.\n- [Huma: OpenAPI Generation](https://huma.rocks/features/openapi-generation/) — як Go-фреймворк,\n  ужитий у проєктах вище, виводить опис із типів обробників.\n\n\u003chttps://engineer.company/uk/glossary/openapi/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Що таке OpenAPI, як один файл живить документацію, клієнти й моки, чого коштує тримати його правдивим і які помилки дають йому розійтися з кодом.","formats":{"gemtext":"https://engineer.company/uk/glossary/openapi/index.gmi","gopher":"https://engineer.company/uk/glossary/openapi/gophermap","html":"https://engineer.company/uk/glossary/openapi/","json":"https://engineer.company/uk/glossary/openapi/index.json","markdown":"https://engineer.company/uk/glossary/openapi/index.md","pdf":"https://engineer.company/uk/glossary/openapi/index.pdf"},"kind":"page","language":"uk","title":"Що таке OpenAPI?","url":"https://engineer.company/uk/glossary/openapi/","version":1}