Що таке OpenAPI і навіщо описувати API специфікацією?

OpenAPI (раніше Swagger) - стандартний машиночитний формат опису HTTP API у YAML чи JSON: ендпойнти, параметри, тіла запитів і відповідей, коди статусу, автентифікація.

openapi: 3.1.0
info:
  title: Vacancies API
  version: 1.0.0
paths:
  /vacancies/{id}:
    get:
      summary: Отримати вакансію
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Вакансія
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Vacancy' }
        '404':
          description: Не знайдено
components:
  schemas:
    Vacancy:
      type: object
      required: [id, title]
      properties:
        id: { type: integer }
        title: { type: string }
        salary_from: { type: [integer, 'null'] }

Що дає специфікація, крім документації:

• інтерактивна документація - Swagger UI, Redoc, Scalar, Stoplight Elements з кнопкою «спробувати запит»;
• генерація клієнтів - типізовані SDK для TypeScript, PHP, мобільних застосунків;
• моки - фронтенд працює з фейковим сервером до готовності бекенду;
• тести й валідація - перевірка, що реальні відповіді відповідають опису;
• лінтинг - автоматична перевірка стилю й помилок у дизайні;
• виявлення змін, що ламають клієнтів, - порівняння версій специфікації в CI;
• імпорт у Postman, Insomnia, Bruno, API-шлюзи.

Версії:

• 3.0 - найпоширеніша в старих інструментах;
• 3.1 (2021) - повна сумісність із JSON Schema 2020-12;
• 3.2 (вересень 2025) - зворотно сумісне розширення 3.1: потокові медіатипи (SSE, JSON Lines), нові поля для тегів, метод QUERY тощо.

Для нових проєктів - 3.1 чи 3.2, з перевіркою, що потрібні інструменти їх підтримують.

Головна цінність - єдине джерело правди про контракт між бекендом і клієнтами, замість вікі-сторінок, які розходяться з кодом через тиждень.

У Laravel специфікацію найчастіше генерують з коду (Scramble, Scribe), а не пишуть вручну.

Докладніше в документації: Специфікація OpenAPI 3.2.0