Модуль 37

Документація API: OpenAPI та Swagger

Ось твій урок у стилі CS50. Приготуйся, зараз ми розберемо цю тему так, що ти захочеш задокументувати навіть свій список покупок!

🎓 УРОК: Документація API: OpenAPI та Swagger

1. 🔥 Вступ: Проблема «Чорної скриньки»

Уявіть ситуацію. Ви — талановитий шеф-кухар (бекенд-розробник). Ви на кухні, готуєте неймовірні страви. А в залі сидить клієнт (фронтенд-розробник або мобільний додаток), який хоче їсти.

Але є одна маленька проблема... У вас немає меню.

Клієнт кричить на кухню: "Дай мені їжу!" Ви питаєте: "Яку саме? Суп? Стейк? Десерт?" Клієнт: "Ну, щось смачне! І я маю 100 гривень!" Ви: "Але стейк коштує 200, а суп я віддаю тільки в обід!"

Це — хаос. Це — біль. Саме так виглядає розробка без документації. Фронтендер пише вам у Slack о другій ночі: "Слухай, а цей ендпоінт приймає userId як рядок чи як число?". Або ще гірше: ви змінили назву поля, нікому не сказали, і весь додаток "впав".

Риторичне питання: Хіба ми хочемо витрачати життя на пояснення того, як працює наш код, замість того, щоб писати новий? Звісно, ні!

Нам потрібен контракт. Нам потрібне Меню. Нам потрібна мова, якою бекенд і фронтенд домовляться раз і назавжди.

І тут на сцену виходять OpenAPI та Swagger.

2. 🧠 Теоретична база (Як це працює під капотом)

Давайте розберемося з термінами, бо їх часто плутають навіть сеньйори.

📜 OpenAPI vs Swagger: У чому різниця?

Уявіть це так: * OpenAPI — це граматика (правила). Це стандарт (специфікація), який каже: "Описуй свої API ось так, у форматі JSON або YAML". Це як правила української мови. * Swagger — це інструменти. Це як Microsoft Word або Google Docs для цієї мови. Swagger UI малює красиву веб-сторіночку, де можна тикати кнопочки, а Swagger Editor допомагає писати цей опис.

Запам’ятай: OpenAPI — це що ми пишемо (стандарт), Swagger — це чим ми користуємося (інструмент).

Як це виглядає "під капотом"?

Насправді, вся ваша документація — це просто один текстовий файл (зазвичай yaml або json). У ньому чітко прописано: 1. Шляхи (Paths): Куди стукати? (наприклад, /users) 2. Методи: Як стукати? (GET, POST, DELETE) 3. Параметри: Що передавати? (ID в URL, JSON в тілі запиту) 4. Відповіді (Responses): Що ми отримаємо? (Дані, помилку 404, успіх 200)

Вам не треба писати PDF-файли. Ви пишете код (структуру), який автоматично перетворюється на красиву інтерактивну інструкцію.

3. 🧪 Приклади (Від простого до реального)

Ми будемо використовувати формат YAML, бо його легше читати людині, ніж JSON (менше дужок, більше відступів).

Приклад 1: "Привіт, світ!"

Уявіть найпростіший сервер, який просто перевіряє, чи ми живі. Питання до тебе: Що нам треба знати, щоб зробити запит? Правильно: URL та метод.

openapi: 3.0.0
info:
  title: Ping API
  version: 1.0.0
paths:
  /ping:
    get:
      summary: Перевірка зв'язку
      responses:
        '200':
          description: Все працює! Сервер відповідає "Pong"

Що ми бачимо: Є шлях /ping. Якщо зробити GET-запит, отримаємо статус 200 (ОК). Все просто.

Приклад 2: Замовлення кави (Реальна ситуація)

Тепер складніше. Ми хочемо замовити каву. Питання: Якщо ми щось замовляємо (створюємо), який HTTP метод ми використаємо? І що нам треба передати бариста? Відповідь: Метод POST. Треба передати назву кави і розмір.

Давайте опишемо це мовою OpenAPI:

paths:
  /order:
    post:
      summary: Замовити каву
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                coffee_type:
                  type: string
                  example: "Latte"
                size:
                  type: string
                  enum: [small, medium, large] # Обмеження вибору!
      responses:
        '201':
          description: Замовлення прийнято
          content:
            application/json:
              schema:
                type: object
                properties:
                  order_id:
                    type: integer
                  message:
                    type: string

Чому це круто? Подивіться на рядок enum: [small, medium, large]. Swagger UI автоматично намалює випадаючий список! Фронтендер фізично не зможе відправити вам розмір "huge", бо документація це забороняє. Ми вирішили проблему ще до написання коду!

4. 🛠 Практична частина

Час закачати рукави. Уявіть, що ви редагуєте цей YAML файл.

Завдання 1: Знайди помилку У прикладі нижче розробник забув вказати тип даних для віку користувача. Як би ти це виправив?

properties:
  username:
    type: string
  age:
    # Тут чогось не вистачає...

Завдання 2: "Суворий контроль" Додай до поля password обмеження, щоб мінімальна довжина була 8 символів. (Підказка: в OpenAPI є властивість minLength).

Завдання 3: Новий статус У прикладі з кавою ми додали відповідь 201 (Created). Але що, якщо кавомашина зламалася? Додай відповідь зі статусом 500 і описом "Внутрішня помилка кавомашини".

Завдання 4: Міні-кейс Напиши фрагмент специфікації для шляху /users/{id}. * Метод: GET * Він має приймати id (ціле число) прямо в шляху (path parameter). * Якщо користувача знайдено — повертає 200. * Якщо ні — повертає 404.

Завдання 5: А що, якщо... Що, якщо ми змінимо назву поля з coffee_type на product_name у документації, але забудемо змінити в коді бекенда? Що станеться, коли фронтенд спробує зробити запит? (Подумай про наслідки розсинхронізації).

5. 💡 Мислення як у розробника

Ось що відрізняє новачка від профі в роботі з документацією.

1. Code-First vs Design-First * Новачок: Спочатку пише код (Python/Java/JS), а потім, коли все готово, сяк-так генерує документацію. Це часто призводить до застарілих доків. * Профі: Часто використовує Design-First. Спочатку ми пишемо YAML файл (OpenAPI). Ми сперечаємося про назви полів до того, як написали хоч рядок коду. Як тільки затвердили файл — бекендер йде писати API, а фронтендер — верстати інтерфейс. Паралельна робота!

2. Документація — це "Єдине Джерело Правди" (Single Source of Truth) Якщо в коді написано одне, а в Swagger — інше, це баг. Документація, яка бреше, гірша за відсутність документації.

3. Не пиши вручну, якщо можеш згенерувати У більшості сучасних фреймворків (FastAPI, NestJS, Spring Boot) ти пишеш код, додаєш пару декораторів/анотацій, і Swagger генерується сам. Це магія, яку треба використовувати.

6. 🧩 Підсумок

Отже, що ми маємо в сухому залишку:

  1. Ми не хочемо хаосу, тому використовуємо контракти.
  2. OpenAPI — це стандарт (наш закон).
  3. Swagger — це візуалізатор (наш красивий інтерфейс для закону).
  4. Це економить години суперечок і мільйони нервових клітин.

Що ти тепер вмієш? Ти можеш відкрити будь-яку документацію API (Stripe, Google Maps, Twitter) і не злякатися. Ти розумієш, де шукати методи, параметри і що очікувати у відповідь. Ти став "писемним" у світі API.

🚀 Тизер наступного уроку: Добре, ми описали, як виглядає запит. Але як переконатися, що користувач має право робити цей запит? На наступному уроці ми поговоримо про фейс-контроль у світі вебу: Автентифікація, JWT токени та безпека API.

До зустрічі! Це був CS50... тобто, твій персональний урок!

← До списку уроків Наступний урок →