Vincule especificações OpenAPI, gRPC e AsyncAPI ao seu modelo C4

Algumas semanas atrás, eu estava revisando uma arquitetura de sistema com uma equipe que tinha um diagrama C4 lindo. Os containers estavam bem definidos. Os relacionamentos tinham rótulos claros. Tudo parecia ótimo — ate alguém perguntar "como é a API entre o Serviço de Pedidos e o Gateway de Pagamento?"

Silencio. O diagrama dizia "REST/JSON." A especificação OpenAPI vivia em outro repositório. A lista real de endpoints estava em uma pagina do Notion que não era atualizada desde que o ultimo estagiário saiu. Três fontes de verdade para uma superfície de API, e nenhuma delas concordava.

Isso é absurdamente comum. Especificações de API são alguns dos artefatos mais precisos e legíveis por maquina em um codebase. No entanto, na documentação de arquitetura, são invisíveis. Você tem uma caixa, uma seta e um rotulo de protocolo. O contrato real — os endpoints, os schemas, os campos — vive em outro lugar completamente.

Construímos Contratos de API para corrigir isso. Suas especificações de API agora vivem dentro da sua arquitetura, vinculadas aos elementos que as implementam e consomem.

Quatro Protocolos, Um Lar

Sistemas modernos raramente falam um único protocolo. Sua API publica e REST, seus serviços internos se comunicam via gRPC e seu frontend busca dados através de GraphQL. Cada um tem seu próprio formato de especificação, suas próprias ferramentas, seu próprio ecossistema de documentação.

Os Contratos de API do Archyl suportam todos os quatro:

OpenAPI / Swagger — Importe suas especificações OpenAPI 3.x ou Swagger 2.0 e obtenha um visualizador de referencia interativo alimentado pelo Scalar. Endpoints são agrupados, parâmetros são documentados, schemas são expandiveis. E a mesma experiencia que você teria com uma ferramenta dedicada de documentação de API, incorporada diretamente no seu workspace de arquitetura.

gRPC / Protocol Buffers — Cole ou sincronize suas definições .proto. O visualizador renderiza serviços, métodos, tipos de mensagem e enums com destaque de sintaxe e indentacao adequada. Chega de procurar em arquivos proto para entender o que um serviço expõe.

GraphQL — Importe seu schema e explore tipos, queries, mutations e subscriptions. E se você configurou endpoints de servidor, obtém um playground GraphiQL completo — escreva queries, execute-as contra sua API real e explore o schema interativamente, tudo sem sair do Archyl.

AsyncAPI — Defina suas APIs orientadas a eventos com especificações AsyncAPI. O visualizador renderiza canais, operações, schemas de mensagens e bindings de servidor com destaque de sintaxe completo. Seja usando Kafka, RabbitMQ, NATS ou WebSockets, contratos AsyncAPI documentam quais eventos seus serviços produzem e consomem.

Importar do Git ou Colar Diretamente

Especificações de API mudam. Um endpoint é adicionado, um campo é descontinuado, uma nova versão é lancada. Se sua documentação requer copiar e colar manualmente para se manter atualizada, ela não vai se manter atualizada.

Por isso os Contratos de API suportam dois modos de origem:

Sincronização Git conecta seu contrato a um arquivo de especificação em um repositório. Aponte para seu openapi.yaml, seu service.proto, seu schema.graphql ou seu asyncapi.yaml, e o Archyl busca o conteúdo diretamente. Quando a especificação muda na origem, clique em sincronizar e o contrato se atualiza. Isso funciona com todos os provedores git que o Archyl suporta — GitHub, GitLab, Bitbucket, Azure DevOps e instancias auto-hospedadas.

Manual e para equipes que não mantém especificações no git, ou para prototipagem rápida. Cole o conteúdo da especificação diretamente e edite no local. Útil para rascunhar um contrato antes do serviço existir, ou para importar uma especificação de uma API de terceiros que você não controla.

Ambos os modos suportam versionamento, para que você possa rastrear qual versão do contrato está documentando.

Vinculado a Sua Arquitetura

Aqui é onde os Contratos de API se tornam mais do que um visualizador de especificações.

Cada contrato pode ser vinculado a um ou mais elementos C4 — sistemas, containers, componentes ou elementos de código. Uma especificação OpenAPI pode ser vinculada ao container API Gateway que a serve. Um proto gRPC pode ser vinculado ao componente de microsserviço que o implementa. Um schema GraphQL pode ser vinculado ao BFF (Backend for Frontend) que o expõe.

Esses vínculos são bidirecionais. A partir do contrato, você vê quais elementos de arquitetura ele se relaciona. A partir do painel de detalhes do elemento no diagrama, você vê quais contratos descrevem sua superfície de API. Quando você clica com o botão direito em um container no canvas, pode vincular e desvincular contratos diretamente do menu de contexto.

Isso fecha a lacuna que descrevi no inicio. Quando alguém pergunta "como é a API entre esses dois serviços?", a resposta está a um clique de distancia. Não em uma ferramenta diferente, não em um repo diferente — ali mesmo no diagrama.

Canais de Eventos

Arquiteturas orientadas a eventos são notoriamente difíceis de documentar. Qual serviço publica em qual tópico? Qual é o schema da mensagem? Quem consome?

Os Canais de Eventos do Archyl trazem visibilidade para sua comunicação assíncrona. Cada contrato AsyncAPI automaticamente expõe os canais que define — tópicos, filas, streams — e os mapeia para os elementos C4 que produzem e consomem eventos.

No diagrama, canais de eventos aparecem como tipos de conexão distintos, tornando imediatamente claro quais relacionamentos são chamadas de API síncronas e quais são fluxos de eventos assíncronos. Isso é critico para entender o comportamento do sistema: uma chamada REST entre dois serviços tem características de confiabilidade e acoplamento muito diferentes de um evento publicado em um message broker.

Você também pode criar canais de eventos independentemente dos contratos AsyncAPI, útil para documentar sistemas de mensageria legados ou protocolos proprietários que não têm uma especificação formal.

Visualizadores Interativos

Não queríamos que contratos fossem blocos de texto bruto. Cada protocolo recebe um visualizador construído especificamente:

O visualizador OpenAPI renderiza uma referencia de API totalmente interativa. Endpoints são organizados por tag, com schemas de requisicao/resposta expandiveis, documentação de parâmetros e detalhes de autenticação. Se você definiu URLs de servidor, o visualizador as mostra para que desenvolvedores saibam para onde enviar requisições. E uma experiencia real de documentação de API, não apenas um YAML com destaque de sintaxe.

O visualizador de Protocol Buffer renderiza definições proto com coloração de sintaxe adequada, tornando serviços, RPCs e estruturas de mensagens fáceis de escanear.

O visualizador GraphQL destaca tipos, campos e diretivas. E quando você configurou um endpoint de servidor, uma segunda aba abre um playground GraphiQL completo. Você pode escrever e executar queries contra sua API ao vivo, explorar o schema através de introspecção e testar mutations — tudo incorporado no Archyl. Se sua API GraphQL tem múltiplos ambientes (staging, produção), você pode definir múltiplas entradas de servidor e alternar entre eles.

O visualizador AsyncAPI renderiza suas definições de API orientada a eventos com listagens de canais, schemas de mensagens e configurações de servidor/broker. Cada canal mostra suas operações (publicar/inscrever), schemas de payload e bindings — dando aos desenvolvedores uma imagem clara da sua superfície de comunicação orientada a eventos.

Como Começar

Navegue ate qualquer projeto e abra a seção Contratos de API na barra lateral. Clique em "Adicionar Contrato" e escolha seu tipo de protocolo e modo de origem.

Para contratos originados do git, conecte um repositório (ou reutilize um já conectado ao seu projeto), especifique o caminho do arquivo e a branch, e o Archyl busca a especificação. Para contratos manuais, cole o conteúdo diretamente.

Uma vez criado, vá ao diagrama e vincule o contrato aos elementos C4 relevantes. A partir desse ponto, qualquer pessoa explorando a arquitetura pode acessar a superfície real da API diretamente do diagrama.

Por Que Isso Importa

Diagramas de arquitetura são poderosos para mostrar estrutura — o que existe e como as coisas se conectam. Mas sempre foram fracos em interfaces. Uma seta de relacionamento rotulada como "REST/HTTPS" diz quase nada sobre o que realmente flui entre dois serviços. Um evento publicado em um tópico Kafka é ainda mais opaco — a menos que você tenha a especificação AsyncAPI e o mapeamento de canais bem ali.

Contratos de API preenchem essa lacuna. Eles adicionam precisão as setas. Quando um novo membro da equipe olha sua arquitetura e vê uma conexão entre o App Móvel e o API Gateway, ele pode imediatamente abrir a especificação OpenAPI e entender exatamente quais endpoints estão disponíveis, quais estruturas de dados são trocadas e qual autenticação é necessária.

Esta e documentação de arquitetura que justifica sua existência. Não porque alguém a mandou fazer, mas porque responde perguntas reais que surgem todos os dias.

Ja usa o Archyl para sua arquitetura? Explore o recurso de Contratos de API no seu projeto. Novo na plataforma? Aprenda sobre o modelo C4 e como a descoberta com IA pode gerar seu diagrama de arquitetura automaticamente.