Documentação API: OpenAPI, Swagger, Postman

TL; DR

O contrato SDK Mookie testes portal.
Swagger UI/Redoc - vitrine de leitura; Postman - cenários executáveis.
Usamos linterners, breaking-checks, exemplos e esquemas de erro, geramos servidores SDK e Mock, publicamos um portal com versioning e «Sunset».

1) Objetivos e princípios

Contrato um (OpenAPI). O resto é gerado.
Documentação executável: exemplos de solicitações de teste no Postman/CLI.
Segurança padrão: esquemas de erro, limites, autenticação.
Versioning e ciclo de vida: 'v1 '/' v2', Deprecation/Sunset, changelog.

2) Estrutura de OpenAPI (esqueleto mínimo)

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

• Coloque o schemas/responses/parameters/requestBodies em 'componentes'.
• Descreva o securitySchemes (OAuth2/JWT/HMAC) e aplique no nível 'paths '/' global'.

3) Padrão de erro e metadados

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 }

Sempre documente 429 (rate limit), 401/403, e os títulos «X-RateLimit -», «Retry-After».

4) Exemplos: request/response, curl e SDK

Para cada endpoint, um exemplo mínimo e estendido.
Gere curl e código-snippets (JS/Python/Go) a partir de OpenAPI; Não escrevam com as mãos.
Aplique valores reais: UUID, data ISO, quantias em «menores» (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 - como publicar

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

2. Redoc (páginas longas de leitura).

Incluir tópico escuro, pesquisa, seletor de versões ('v1', 'v2'), banner Deprecation.

Crie «Try it out» para o domínio prod, permita-o no sandbox.

6) Colecções Postman: cenários ao vivo

Gere automaticamente uma coleção de e suporte variáveis de ambientes ('se você não quiser que isso aconteça.
Adicione pretextos (obtenção de token) e testes pós-teste (assert status/esquema).
Divida as pastas Auth, Payments, Payouts, Webhooks.
Exporte monitores (programados) para rotas críticas.

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 e sandbox

Gere um servidor mock a partir de OpenAPI (por exemplo/' example '/' example ').
Especifique as limitações dos mooks, idempotação, atrasos, erros aleatórios (para UAT).
Documente as diferenças de sandbox vs prod (limites, dados, atrasos).

8) Geração automática SDK

De OpenAPI, gere SDK (TypeScript, Python, Go).
Política de lançamento SDK = SemVer, mapping para API.
Em README SDK: autenticação, retraí, idempotação, processamento 429/Retry-After.

9) Linting, verificação de quebras e CI

Linters: espectral (estilos/anti-pattern), openapi-diff (breaking-checks).

• validador de esquema,
• linter,
• contracto de testes contra o servidor MK,
• montagem Swagger/Redoc/coleções,
• publicação no portal (staging→prod),
• Aviso de Deprecation/Sunset.

10) Versioning, Deprecation, Sunset

Versão em URI ('/v1 ') e em' info. version`.
Bandeiras de obsolescência: «Deprecation: true», «Sunset: <RFC123 data>», «Link: <changelog>».
No portal, um banner e um temporizador antes de desligar; Colecções Postman para v1 estão congeladas (apenas bagfixs).

11) Segurança e privacidade na doca

Não publiquem segredos, URL internos, PAN/PII real.
Para campos sensíveis, camuflagem e exemplos-bronca.
Swagger «Try it out» → apenas para sandbox, com rate-limits.
Descreva claramente OAuth2/OIDC, HMAC (para webhooks) e mTLS (se necessário).

12) Contratos em linha

Recursos no plural: '/payments ', '/payouts'.
Identificadores: 'pay _', 'po _', UUIDv4 ou ksuid.
Datas: UTC ISO-8601; dinheiro - 'amount _ menor + currency'.
Paginação - cursor-based ('? cursor = & limit ='), arrumações estáveis.
Idempotidade - 'Idempotency-Key' para mutações.
Objeto 'meta' e 'links' estável para as listas.

13) Seção «Webhooks» na doca

Seção separada com envelope de evento, assinaturas HMAC, janela de tempo, retais, códigos de resposta.
Exemplos de corpo de evento e coleção do Postman para verificação local de assinatura.
Endpoints replay/DLQ e folha de cheque UAT.

14) Portal de Dave: papéis e publicação

Seções: Visão, Início, Autenticação, Endpoint, Exemplos, Webhooks, SDK, Restrições, Changelog.
Papéis: API Steward (padrões), Domain Owner (conteúdo), Tech Writer (edição), DevRel (portal/comunidade).
Fisch: Pesquisa por campos de circuito, cópia de sampls, «recolher um pedido» → Postman.

15) Folhas de cheque

• Está valendo; linter sem erros.
• Exemplos cobrem 200/4xx/429/5xx.
• Segurança: Os circuitos auth são descritos e não há segredos.
• Swagger/Redoc e Postman foram formados.
• SDK gerado e publicado.
• O changelog e o seletor de versões foram atualizados.

• Os títulos do Deprecation/Sunset estão incluídos.
• Banner no portal, e-mails para os parceiros.
• As métricas de chamadas da versão ultrapassada caem para o nível de destino.

16) Anti-pattern

Fontes duplicadas de verdade (viki ≠ OpenAPI).
Exemplos «de olho» sem iniciar no Postman.
Não há um único formato de erro.
Versão em query-parâmetro em vez de URI/domínio.
Swagger com acesso à proda e sem limites.
Paginação e esquemas de autenticação incoerentes.

17) Miniclippets automação

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) Localização e disponibilidade

Individuais 'info. descrição _ <lang> 'ou duas montagens de portal (EN/RU).
Termos em glossário (KYC/AML, payout, idempotency).
Contraste, navegação por teclado, assunto escuro.

Currículo

Junte a linha de montagem da documentação: um único contrato de Adobe API lentes e breaking-checks Swagger/Redoc vitrines do Postman Coleção e o servidor MOK SDK com versioning e Sunset. Exemplos regulares, um único formato de erro e autenticação rigorosa transformarão a documentação de PDF na prateleira em ferramenta de integração de trabalho, acelerando os parceiros e reduzindo o custo de suporte.