Глоссарий

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