Pular para o conteúdo principal

Roadmap AsyncAPI

Proposta de evolução da documentação de eventos de Markdown manual para AsyncAPI (contrato gerado), alinhada à DOCS-ADR-002. Este documento é uma proposta [INFERÊNCIA / planejamento] — nada aqui está implementado.

Por que AsyncAPI​

Hoje os eventos são descritos em Markdown manual (Referência de Webhooks), o que tende a divergir do código com o tempo. AsyncAPI é o equivalente do OpenAPI para mensageria/eventos: descreve canais, mensagens e payloads de forma versionável e gerável, permitindo as mesmas garantias que já temos para a API REST.

Estrutura sugerida de asyncapi.yaml​

Esqueleto ilustrativo; campos concretos devem ser preenchidos pelos times donos dos eventos.

asyncapi: 3.0.0
info:
  title: FinWAY Events
  version: 0.1.0
  description: Eventos de domínio entregues via webhook.
defaultContentType: application/json
channels:
  pix:
    address: PIX
    messages:
      PixCreated: { $ref: '#/components/messages/PixCreated' }
      PixUpdated: { $ref: '#/components/messages/PixUpdated' }
  # charge, account-holder, transaction, individual-person, company, account, product
operations:
  receivePixCreated:
    action: receive          # do ponto de vista do integrador
    channel: { $ref: '#/channels/pix' }
components:
  messages:
    PixCreated:
      name: PIX_CREATED
      payload: { $ref: '#/components/schemas/PixEvent' }
  schemas:
    PixEvent:
      type: object
      # campos conforme o catálogo atual de payloads

Ownership​

  • Cada time dono do domínio mantém os eventos do seu serviço (mesma lógica multi-repo do Blueprint).
  • O portal central agrega os asyncapi.yaml e gera as páginas — sem editar o gerado.
  • [TODO] Definir o repositório fonte de cada asyncapi.yaml (por serviço) e o CODEOWNERS.

Como gerar docs futuramente​

[TODO] Avaliar uma das abordagens (a confirmar na implementação):

  • Plugin Docusaurus para AsyncAPI (geração de páginas a partir de asyncapi.yaml), ou
  • Geração de Markdown/HTML via @asyncapi/cli + template, integrado ao build.

Em ambos os casos: asyncapi.yaml como fonte única, páginas geradas (não editadas à mão), via um script gen:events dedicado. (Diferente da API Reference REST, que é renderizada em runtime pelo Scalar — ver DOCS-ADR-002.)

Checklist de maturidade para eventos​

Para cada evento/domínio, considerar documentar (hoje são lacunas conhecidas):

  • Nome do canal/tópico e do evento
  • Schema do payload (campos, tipos, obrigatoriedade)
  • Assinatura/autenticidade da entrega
  • Retry/reenvio e backoff
  • Idempotência (identificador de evento / deduplicação)
  • Ordenação (garantias por chave/partição)
  • DLQ / tratamento de falhas
  • SLA de entrega
  • Versionamento do schema do evento