Документація 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 на полиці» в робочий інструмент інтеграцій, прискорюючи партнерів і знижуючи вартість підтримки.