Документация API: OpenAPI, Swagger, Postman

TL;DR

OpenAPI — источник истины: контракт → SDK → моки → тесты → портал.
Swagger UI/Redoc — читаемая витрина; Postman — исполняемые сценарии.
Вшиваем линтеры, breaking-checks, примеры и схемы ошибок, генерим SDK и Mock-серверы, публикуем дев-портал с версионированием и «Sunset».

1) Цели и принципы

Контракт один (OpenAPI). Все остальное генерируется.
Документация исполняема: примеры запросов тестируемы в Postman/CLI.
Безопасность по умолчанию: схемы ошибок, лимитов, аутентификации.
Версионирование и жизненный цикл: `v1`/`v2`, Deprecation/Sunset, changelog.

2) Структура OpenAPI (минимальный скелет)

yaml openapi: 3. 0. 3 info:
title: Payments API version: 1. 2. 0 description: >
Payment transactions: auth/capture/refund/payout. All responses contain trace_id.
servers:
- url: https://api. example. com/v1 tags:
- name: Payments
- name: Payouts components:
securitySchemes:
oauth2:
type: oauth2 flows:
clientCredentials:
tokenUrl: https://idp. example. com/oauth/token scopes:
payments: read: read payments: write: write payments schemas:
Error:
type: object required: [error, error_description, trace_id]
properties:
error: { type: string }
error_description: { type: string }
trace_id: { type: string, format: uuid }
security:
- oauth2: [payments:read]
paths:
/payments/{id}:
get:
summary: Receive payment tags: [Payments]
parameters:
- in: path name: id required: true schema: { type: string, format: uuid }
responses:
'200':
description: Content succeeded:
application/json:
schema: { $ref: '#/components/schemas/Payment' }
'404': { $ref: '#/components/responses/NotFound' }
components:
responses:
NotFound:
description: Content not found:
application/json:
schema: { $ref: '#/components/schemas/Error' }

• Раскладывайте schemas/responses/parameters/requestBodies в `components`.
• Описывайте securitySchemes (OAuth2/JWT/HMAC) и применяйте на уровне `paths`/`global`.

3) Стандарт ошибок и метаданные

yaml components:
schemas:
ApiError:
type: object required: [error, error_description, trace_id]
properties:
error: { enum: [invalid_request, not_found, rate_limited, internal] }
error_description: { type: string }
trace_id: { type: string, format: uuid }

Всегда документируйте 429 (rate limit), 401/403, и заголовки `X-RateLimit-`, `Retry-After`.

4) Примеры: request/response, curl и SDK

Для каждого эндпоинта: минимальный и расширенный пример.
Генерируйте curl и код-сниппеты (JS/Python/Go) из OpenAPI; не пишите руками.
Прикладывайте реальные значения: UUID, ISO-дату, суммы в «минорных» (cents).

yaml examples:
ok:
value:
id: "pay_123"
amount_minor: 1099 currency: "EUR"
status: "captured"
created_at: "2025-11-03T12:34:56Z"

5) Swagger UI / Redoc — как публиковать

1. Swagger UI (интерактив, try-it-out),

2. Redoc (читабельные длинные страницы).

Включайте: темную тему, поиск, версионный селектор (`v1`, `v2`), баннер Deprecation.

Скройте «Try it out» для прод-домена, разрешите на sandbox.

6) Postman-коллекции: живые сценарии

Автогенерируйте коллекцию из OpenAPI и поддерживайте переменные окружений (`{{baseUrl}}`, `{{accessToken}}`).
Добавьте претесты (получение токена) и пост-тесты (assert статуса/схем).
Разбейте по папкам: Auth, Payments, Payouts, Webhooks.
Экспортируйте мониторы (по расписанию) для критичных маршрутов.

js pm. test("status is 200", () => pm. response. code === 200);
pm. test("schema valid", () => tv4. validate(pm. response. json(), pm. collectionVariables. get("schema_payment")));

7) Моки и сэндбокс

Генерируйте mock-сервер из OpenAPI (по примерам/`example`/`examples`).
Обозначьте ограничения моков: идемпотентность, задержки, случайные ошибки (для UAT).
Документируйте отличия sandbox vs prod (лимиты, данные, задержки).

8) Автогенерация SDK

Из OpenAPI генерируйте официальные SDK (TypeScript, Python, Go).
Политика релизов SDK = SemVer, маппинг на версию API.
В README SDK: аутентификация, ретраи, идемпотентность, обработка 429/Retry-After.

9) Линтинг, проверка ломаний и CI

Линтеры: spectral (стили/анти-паттерны), openapi-diff (breaking-checks).

• валидатор схемы,
• линтер,
• contract tests против мок-сервера,
• сборка Swagger/Redoc/коллекции,
• публикация на портал (staging→prod),
• оповещение о Deprecation/Sunset.

10) Версионирование, Deprecation, Sunset

Версия в URI (`/v1`) и в `info.version`.
Флаги устаревания: заголовки `Deprecation: true`, `Sunset: <RFC1123 date>`, `Link: <changelog>`.
В портале — баннер и таймер до отключения; Postman-коллекции для v1 заморожены (только багфиксы).

11) Безопасность и приватность в доке

Не публикуйте секреты, внутренние URL, реальные PAN/PII.
Для чувствительных полей — маскировка и примеры-заглушки.
Swagger «Try it out» → только к sandbox, с rate-limits.
Четко описывайте OAuth2/OIDC, HMAC (для вебхуков) и mTLS (если требуется).

12) Стайл-гайд контрактов

Ресурсы во множественном числе: `/payments`, `/payouts`.
Идентификаторы: `pay_`, `po_`, UUIDv4 или ksuid.
Даты — UTC ISO-8601; деньги — `amount_minor + currency`.
Пагинация — cursor-based (`?cursor=&limit=`), стабильные сортировки.
Идемпотентность — `Idempotency-Key` для мутаций.
Стабильный объект `meta` и `links` для списков.

13) Раздел «Webhooks» в доке

Отдельный раздел с конвертом события, подписями HMAC, окном времени, ретраями, кодами ответов.
Примеры тел событий и коллекция Postman для локальной проверки подписи.
Эндпоинты replay/DLQ и чек-лист UAT.

14) Дев-портал: роли и публикация

Разделы: Обзор, Начало работы, Аутентификация, Эндпоинты, Примеры, Вебхуки, SDK, Ограничения, Changelog.
Роли: API Steward (стандарты), Domain Owner (контент), Tech Writer (редактура), DevRel (портал/сообщество).
Фича: поиск по полям схем, копирование сэмплов, «собрать запрос» → Postman.

15) Чек-листы

• OpenAPI валиден; линтер без ошибок.
• Примеры покрывают 200/4xx/429/5xx.
• Безопасность: описаны схемы auth, нет секретов.
• Сформированы Swagger/Redoc и Postman (prod/sandbox).
• Сгенерированы SDK и опубликованы.
• Обновлены changelog и версионный селектор.

• Заголовки Deprecation/Sunset включены.
• Баннер в портале, письма партнерам.
• Метрики вызовов устаревшей версии падают к целевому уровню.

16) Анти-паттерны

Дублирующие источники истины (вики ≠ OpenAPI).
Примеры «на глаз» без запуска в Postman.
Отсутствие единого формата ошибок.
Версия «в query-параметре» вместо URI/домена.
Swagger с доступом в прод и без лимитов.
Несогласованная пагинация и схемы аутентификации.

17) Мини-сниппеты автоматизации

bash openapi2postmanv2 -s openapi. yaml -o postman. json -p

yaml steps:
- run: spectral lint openapi. yaml
- run: openapi-diff --fail-on-breaking main. yaml openapi. yaml
- run: redoc-cli bundle openapi. yaml -o site/redoc. html
- run: swagger-cli bundle openapi. yaml -o site/swagger. json
- run: openapi2postmanv2 -s openapi. yaml -o site/postman. json -p
- run: npm run deploy:portal

18) Локализация и доступность

Отдельные `info.description_<lang>` или две сборки портала (EN/RU).
Термины в глоссарии (KYC/AML, payout, idempotency).
Контраст, клавиатурная навигация, темная тема.

Резюме

Соберите конвейер документации: единый OpenAPI-контракт → линтеры и breaking-checks → Swagger/Redoc витрины → Postman коллекции и мок-сервер → SDK → дев-портал с версионированием и Sunset. Регулярные примеры, единый формат ошибок и строгая аутентификация превратят документацию из «PDF на полке» в рабочий инструмент интеграций, ускоряя партнеров и снижая стоимость поддержки.