Гайды

OpenAPI: спецификация и генерация клиентов

Структура 3.x, components и refs, openapi-generator и orval, Spectral, code-first vs design-first и чек-лист.

~9 мин чтения

Backend OpenAPI Документация API Генерация кода

OpenAPI: спецификация и генерация клиентов

OpenAPI 3.x (бывший Swagger) — YAML/JSON-описание REST API: пути, операции, параметры, тела, ответы, components (переиспользуемые схемы), securitySchemes. Из спецификации генерируют клиенты, серверные заглушки и документацию. FastAPI выдаёт OpenAPI из коробки — Swagger, ReDoc и метаданные в FastAPI.

1. Структура документа

yaml

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders/{orderId}:
    get:
      summary: Получить заказ
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
components:
  schemas:
    Order:
      type: object
      required: [id, status]
      properties:
        id: { type: integer }
        status: { type: string, enum: [pending, paid] }

2. Переиспользование

$ref на components/schemas, parameters, responses уменьшают дублирование и расхождения с реализацией.

3. Генерация клиентов

Инструменты:

openapi-generator — много языков (TypeScript axios, Python, Go…).
openapi-typescript — только типы TS из схемы.
orval — React Query + TS из OpenAPI.

Типичный CI: при изменении спецификации — PR с сгенерированным diff клиента.

4. Генерация сервера

OpenAPI Generator умеет server stubs (например Python Flask/FastAPI шаблоны) — старт для mock-сервера; бизнес-логику всё равно пишут руками.

5. Валидация контракта

Spectral — линтер OpenAPI (правила именования, наличие operationId, security).
Schemathesis — property-based тесты по схеме против running API.

6. Синхронизация с кодом

Подход	Идея
Code-first (FastAPI, Springdoc)	Код → OpenAPI; экспорт в файл для клиентов
Design-first	OpenAPI → ревью → codegen / ручная реализация

Выберите один источник правды и автоматизируйте проверку дрейфа.

Breaking changes: удаление поля, смена типа, обязательность нового поля — мажорная версия API (/v2 или info.version). В CI сравнивайте спецификации инструментами вроде oasdiff / openapi-diff и блокируйте непомеченные ломающие изменения.

7. Версии OpenAPI

3.1 совместим с JSON Schema чуть ближе; убедитесь, что toolchain поддерживает вашу версию.

8. Чек-лист

У каждой операции operationId для codegen.
Общие ошибки в components/responses.
Security: bearerAuth, oauth2 описаны и совпадают с продом.
Спецификация публикуется в CI артефакте или registry.

Дальше: REST: HATEOAS и версии · тег OpenAPI