Глосарій

OpenAPI / Swagger

OpenAPI — стандарт машинозчитуваного опису REST API у форматі YAML або JSON. Swagger — набір інструментів навколо цього стандарту (Swagger UI, Swagger Editor). Документація, що не застаріває, бо генерується з коду або є джерелом правди для генерації коду.

Що дає

Інтерактивна документація (Swagger UI) — можна тестувати endpoint-и прямо в браузері
Генерація клієнтських SDK — автоматичний TypeScript/Python/PHP-клієнт з описів API
Валідація запитів і відповідей на відповідність специфікації
Договір між frontend і backend — спочатку описуємо API, потім реалізуємо

Мінімальний приклад

paths:
  /users/{id}:
    get:
      summary: Отримати користувача
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer