API documentation: OpenAPI, Swagger, Postman

TL; DR

OpenAPI - source of truth: contract → SDK → moki → tests → portal.
Swagger UI/Redoc - readable showcase; Postman - executable scripts.

We sew in linters, breaking-checks, examples and error schemes, generate SDKs and Mock servers, publish a versioned dev portal and "Sunset."

1) Goals and principles

Contract one (OpenAPI). Everything else is generated.
Documentation is executable: sample requests are tested in Postman/CLI.
Default security: error schemes, limits, authentication.
Versioning and life cycle: 'v1 '/' v2', Deprecation/Sunset, changelog.

2) OpenAPI structure (minimum skeleton)

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' }

• Decompose schemas/responses/parameters/requestBodies into'components'.
• Describe securitySchemes (OAuth2/JWT/HMAC) and apply at the 'paths '/' global' level.

3) Error standard and metadata

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 }

Always document 429 (rate limit), 401/403, and the headers' X-RateLimit- ',' Retry-After '.

4) Examples: request/response, curl and SDK

For each endpoint: minimum and extended example.
Generate curl and code snippets (JS/Python/Go) from OpenAPI; do not write with your hands.
Apply real values: UUID, ISO-date, sums in "minor" (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 - how to post

1. Swagger UI (interactive, try-it-out),

2. Redoc (readable long pages).

Include: dark theme, search, version selector ('v1', 'v2'), Deprecation banner.

Hide "Try it out" for the production domain, allow on the sandbox.

6) Postman collections: Live scripts

Autogenerate the collection from OpenAPI and support environment variables ('{{baseUrl}}', '{{accessToken}}').
Add pretests (obtaining a token) and post-tests (assert status/schemas).
Break into folders: Auth, Payments, Payouts, Webhooks.
Export monitors (scheduled) for critical routes.

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) Moki and the sandbox

Generate a mock server from OpenAPI (examples/' example '/' examples').
Indicate the limitations of the mocs: idempotency, delays, random errors (for UAT).
Document sandbox vs prod differences (limits, data, delays).

8) SDK autogeneration

From OpenAPI, generate official SDKs (TypeScript, Python, Go).
SDK release policy = SemVer, API version mapping.
In the README SDK: authentication, retray, idempotency, 429/Retry-After processing.

9) Linting, breakage check and CI

Linters: spectral (styles/anti-patterns), openapi-diff (breaking-checks).

• circuit validator,
• linter,
• contract tests against the ioc server,
• Swagger/Redoc/collection assembly,
• publishing to the portal (staging→prod),
• Deprecation/Sunset alert.

10) Versioning, Deprecation, Sunset

Version in URI ('/v1 ') and in' info. version`.
Deprecation flags: 'Deprecation: true', 'Sunset: <RFC1123 date>', 'Link: <changelog>' headers.
In the portal - a banner and a timer before disconnection; Postman collections for v1 are frozen (bug fixes only).

11) Security and privacy at the dock

Don't post secrets, internal URLs, real PAN/PII.
For sensitive fields - masking and stub examples.
Swagger "Try it out" → only to sandbox, with rate-limits.
Clearly describe OAuth2/OIDC, HMAC (for webhooks) and mTLS (if required).

12) Style Guide contracts

Resources plural: '/payments', '/payouts'.
Identifiers: 'pay _', 'po _', UUIDv4 or ksuid.
Dates - UTC ISO-8601; money - 'amount _ minor + currency'.
Pagination - cursor-based ('? cursor = & limit ='), stable sorting.
Idempotency - 'Idempotency-Key' for mutations.
Stable object'meta' and 'links' for lists.

13) The "Webhooks" section of the dock

Separate section with event envelope, HMAC signatures, time window, retrays, response codes.
Sample event bodies and Postman collection for local signature verification.
replay/DLQ endpoints and UAT checklist.

14) Dev Portal: Roles and Publication

Sections: Overview, Getting Started, Authentication, Endpoints, Examples, Webhooks, SDK, Restrictions, Changelog.
Roles: Steward API (standards), Domain Owner (content), Tech Writer (editing), DevRel (portal/community).
Feature: search through schema fields, copy samples, "collect request" → Postman.

15) Checklists

• OpenAPI is valid; linter without errors.
• Examples cover 200/4xx/429/5xx.
• Security: auth schemes described, no secrets.
• Formed Swagger/Redoc and Postman (prod/sandbox).
• SDK generated and published.
• Updated changelog and version selector.

• Deprecation/Sunset headers included.
• Banner in the portal, letters to partners.
• Legacy call metrics fall to target.

16) Anti-patterns

Duplicate sources of truth (wiki ≠ OpenAPI).
Examples of "by eye" without running in Postman.
Lack of a single error format.
Version "in query parameter" instead of URI/domain.
Swagger with access to food and no limits.
Inconsistent pagination and authentication schemes.

17) Mini snippets of automation

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) Localization and availability

Individual'info. description_<lang>' or two portal assemblies (EN/RU).
Glossary terms (KYC/AML, payout, idempotency).
Contrast, keyboard navigation, dark theme.

Summary

Assemble a pipeline of documentation: a single OpenAPI contract → linters and breaking-checks → Swagger/Redoc showcases → Postman collections and a mock server → SDK → a version portal and Sunset. Regular examples, a single error format, and strong authentication will transform documentation from PDF on the shelf to a working integration tool, speeding up partners and reducing support costs.