intermediate

OpenAPI contracts

Используйте OpenAPI как reviewed contract для documentation, client generation, mocks, validation и contract testing.

OpenAPI (Swagger) описывает HTTP API как machine-readable contract: paths, methods, parameters, request/response schemas, security schemes и examples. Spec — проверенный source of truth, а не постфактумный экспорт.

					paths:
  /orders:
    post:
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrder'
      responses:
        '201':
          description: Created
          headers:
            Location:
              schema: { type: string }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

Применение в lifecycle:

**Documentation** (Redoc, Swagger UI) с examples.
**Client/server codegen** (types, fetch wrappers) — учитывайте ограничения codegen.
**Request validation** middleware из schemas.
**Contract tests** и CI на breaking changes (oasdiff, openapi-diff).
**Mocks** для параллельной frontend-работы.

На интервью: code-first vs design-first, как не допустить drift spec от implementation, что выносить в components/schemas.

Типовые ошибки: автогенерированный spec без constraints, нет examples, версионирование всего monolith spec без владения, codegen с неверным required/optional.

Компромисс: поддержка spec против боли интеграции — автоматизируйте validation в CI для согласованности spec и кода.

Чеклист:

Один проверенный OpenAPI на API surface.
Переиспользуемые components/schemas и securitySchemes.
Examples на критичных operations.
CI падает на непреднамеренные breaking changes.