Contratos de API - Archyl Docs

Documente e gerencie especificações de API vinculadas diretamente aos seus elementos de arquitetura C4

Contratos de API

Os Contratos de API permitem anexar especificações de API aos seus elementos de arquitetura, mantendo documentação e design sincronizados. O Archyl suporta contratos OpenAPI (REST), gRPC, GraphQL e AsyncAPI, com sincronização opcional via git.

Tipos de Contrato Suportados

Tipo Formato Caso de Uso
HTTP (REST) OpenAPI 3.x (YAML/JSON) APIs REST, webhooks
gRPC Protocol Buffers (.proto) RPC entre serviços
GraphQL GraphQL SDL (.graphql) APIs de consulta
Async AsyncAPI (YAML/JSON) APIs orientadas a eventos, filas de mensagens

Criando um Contrato

Entrada Manual

  1. Navegue até seu projeto
  2. Abra a aba Contratos de API
  3. Clique em Novo Contrato
  4. Preencha os detalhes do contrato:
    • Nome — Um nome descritivo (ex.: "API do User Service")
    • Tipo — HTTP, gRPC, GraphQL ou Async
    • Versão — Versão semântica (ex.: 1.0.0)
    • Endpoint — URL base da API
    • Descrição — O que a API faz
  5. Cole ou escreva o conteúdo da especificação no editor
  6. Clique em Criar

Sincronização via Git

Em vez de manter contratos manualmente, você pode sincronizá-los a partir de um repositório git:

  1. Clique em Novo Contrato e selecione Git como tipo de fonte
  2. Escolha um repositório conectado
  3. Especifique o caminho do arquivo de especificação (ex.: api/openapi.yaml)
  4. Defina o branch a rastrear (padrão é o branch padrão do repositório)
  5. O Archyl puxa o conteúdo da especificação e o mantém sincronizado

Você também pode usar padrões glob para corresponder a múltiplos arquivos. Por exemplo, api/**/*.yaml corresponderá a todos os arquivos YAML no diretório api/.

Comportamento da Sincronização

  • As especificações são buscadas do repositório quando o contrato é criado
  • Use o botão Sincronizar para puxar manualmente a versão mais recente
  • O timestamp da última sincronização é exibido no cartão do contrato

Vinculando Contratos à Arquitetura

Os contratos de API se tornam significativos quando vinculados aos elementos C4 que eles descrevem. Um contrato pode ser vinculado a sistemas, containers, componentes ou elementos de código.

Adicionando Vínculos

  1. Abra a página de detalhes de um contrato
  2. Clique em Vincular a Elemento
  3. Selecione o nível C4 (Sistema, Container, Componente ou Código)
  4. Escolha o elemento de destino
  5. O vínculo aparece tanto no contrato quanto no painel de detalhes do elemento

Visualizando Contratos Vinculados

No diagrama, clique com o botão direito em qualquer elemento para abrir seu painel de detalhes. Os contratos de API vinculados aparecem na seção Contratos com:

  • Nome e versão do contrato
  • Badge do tipo de protocolo (HTTP, gRPC, GraphQL, Async)
  • Link para a especificação completa

Entradas de Servidor

Cada contrato pode definir múltiplas entradas de servidor — útil para documentar diferentes ambientes ou regiões.

Campo Descrição
URL A URL base do servidor (ex.: https://api.example.com/v1)
Descrição Ambiente ou propósito (ex.: "Produção", "Staging")

O Visualizador de Especificações

O Archyl renderiza suas especificações de API com um visualizador interativo:

  • OpenAPI — Endpoints agrupados por tag, com schemas de requisição/resposta, parâmetros e exemplos
  • gRPC — Definições de serviço, métodos RPC e tipos de mensagem
  • GraphQL — Tipos, queries, mutations e subscriptions
  • AsyncAPI — Canais, mensagens e schemas

O visualizador é somente leitura e sempre reflete o conteúdo atual do contrato.

Canais de Eventos

Os canais de eventos documentam o lado de mensageria assíncrona da sua arquitetura — tópicos Kafka, filas SQS, exchanges RabbitMQ e similares.

Criando um Canal de Eventos

  1. Navegue até seu projeto
  2. Abra a aba Canais de Eventos
  3. Clique em Novo Canal
  4. Configure o canal:
Campo Descrição
Nome Nome do canal (ex.: "Eventos de Pedido Criado")
Direção produce ou consume
Tipo de Broker Kafka, NATS, SQS, RabbitMQ, Redis, Pulsar ou Personalizado
Nome do Tópico O nome real do tópico ou fila
Formato do Schema JSON Schema, Avro, Protobuf ou Texto
Schema de Valor A definição do schema do payload do evento

Vinculando à Arquitetura

Os canais de eventos seguem o mesmo modelo de vinculação dos contratos de API. Vincule um canal aos sistemas, containers ou componentes que produzem ou consomem seus eventos. Isso torna os fluxos de mensagens visíveis diretamente no diagrama de arquitetura.

Boas Práticas

Mantenha as Especificações Atualizadas

  • Use sincronização via git para especificações que vivem no código
  • Versione seus contratos seguindo versionamento semântico
  • Atualize o contrato quando a API mudar

Vincule Tudo

  • Todo container que serve uma API deve ter pelo menos um contrato vinculado
  • Vincule canais de eventos tanto a produtores quanto a consumidores
  • Use vínculos para tornar o diagrama autodocumentado

Organize por Serviço

  • Um contrato por serviço ou contexto delimitado
  • Use nomes descritivos que correspondam à nomenclatura da sua arquitetura
  • Inclua a versão da API no campo de versão do contrato

Documente os Servidores

  • Adicione entradas de servidor para cada ambiente
  • Inclua endpoints internos e externos
  • Mantenha as URLs atualizadas conforme a infraestrutura muda

Próximos Passos