OpenAPI-контракт

OpenAPI является главным машиночитаемым описанием consumer-facing интерфейса. Документация Publisher, runtime configuration и реализация должны соответствовать одной версии контракта.

Обязательное содержание

• info.title, description и semantic version;
• servers или правила формирования environment URL;
• paths, HTTP methods и operation IDs;
• request parameters и request body schemas;
• success и error responses;
• security schemes и scopes;
• примеры без чувствительных данных;
• ограничения полей, formats и enums.

Naming

• paths — lowercase, понятные существительные;
• JSON fields — camelCase;
• operation IDs — стабильные и уникальные;
• actions не кодируются в path без необходимости;
• внутренняя топология, Kafka topics и adapter names не раскрываются Consumer.

Data conventions

Ошибки

Каждая операция документирует возможные 4xx и 5xx, а не только успешный ответ. Error model должна содержать стабильный machine-readable code, понятное message и request identifier для поддержки.

ErrorResponse:
  type: object
  required: [code, message, requestId]
  properties:
    code:
      type: string
      example: INVALID_REQUEST
    message:
      type: string
    requestId:
      type: string

Совместимость

Без major version разрешаются только обратно совместимые изменения, например новые optional fields. Consumer должен игнорировать неизвестные поля.

Breaking changes требуют новой major version и согласованного overlap/deprecation period. Зафиксированный в ранних материалах шестимесячный overlap следует применять только после утверждения lifecycle policy.

Review checklist

• schema валидна;
• examples проходят schema validation;
• обязательность полей согласована;
• security применяется к нужным operations;
• documented errors реализуемы;
• отсутствуют internal URLs, secrets и персональные данные;
• operation IDs и paths следуют naming policy;
• version соответствует масштабу изменения.