Documentation и contract testing

Durable API защищают consumers **точной документацией**, **рабочими примерами** и **автоматическими contract checks** — не надеждой, что команды читают Slack.

Сущности документации:

• Quickstart с auth и первым успешным вызовом.
• Каталог ошибок со стабильными codes.
• Changelog с датами deprecation.
• OpenAPI/GraphQL schema из того же артефакта, что валидирует CI.

Слои contract testing:

• **Provider tests**: implementation соответствует опубликованной schema (response validation).
• **Consumer-driven contracts** (Pact): ожидания consumer записаны; provider проверяет fixtures.
• **Compatibility CI**: diff OpenAPI/proto в PR; fail на breaking без major version.

					// Supertest + schema assertion example
const res = await request(app).get('/orders/1').expect(200);
expect(res.body).toMatchSchema(orderSchema);
				

Mocks: из OpenAPI (Prism, MSW handlers) для параллельной разработки — обновляйте при смене spec.

На интервью: contract tests vs широкий E2E, владение контрактом в microservices, предотвращение spec drift.

Типовые ошибки: docs отстают от кода, examples не гоняются в CI, pact tests без обновлений, breaking changes без уведомления consumers.

Компромисс: время CI против сюрпризов интеграции — contract tests дешевле production outages.

Чеклист:

• Examples в CI где возможно.
• Обнаружение breaking changes на schemas.
• Consumer fixtures или pact для cross-team API.
• Опубликованные changelog + deprecation policy.