Collega le specifiche OpenAPI, gRPC e AsyncAPI al tuo modello C4

Qualche settimana fa stavo revisionando un'architettura di sistema con un team che aveva un bellissimo diagramma C4. I container erano ben definiti. Le relazioni avevano etichette chiare. Tutto sembrava perfetto — finché qualcuno non ha chiesto "com'è fatta l'API tra il Servizio Ordini e il Gateway di Pagamento?"

Silenzio. Il diagramma diceva "REST/JSON." La specifica OpenAPI viveva in un altro repository. L'elenco effettivo degli endpoint era in una pagina Notion che non veniva aggiornata da quando l'ultimo stagista se n'era andato. Tre fonti di verità per una superficie API, e nessuna di esse concordava.

Questo è assurdamente comune. Le specifiche API sono tra gli artefatti più precisi e leggibili dalle macchine in un codebase. Eppure nella documentazione dell'architettura sono invisibili. Hai una scatola, una freccia e un'etichetta di protocollo. Il contratto effettivo — gli endpoint, gli schema, i campi — vive da un'altra parte.

Abbiamo costruito i Contratti API per risolvere questo problema. Le tue specifiche API ora vivono dentro la tua architettura, collegate agli elementi che le implementano e le consumano.

Quattro Protocolli, Una Casa

I sistemi moderni raramente parlano un singolo protocollo. La tua API pubblica e REST, i tuoi servizi interni comunicano via gRPC, e il tuo frontend recupera dati tramite GraphQL. Ciascuno ha il proprio formato di specifica, i propri strumenti, il proprio ecosistema di documentazione.

I Contratti API di Archyl supportano tutti e quattro:

OpenAPI / Swagger — Importa le tue specifiche OpenAPI 3.x o Swagger 2.0 e ottieni un visualizzatore di riferimento interattivo alimentato da Scalar. Gli endpoint sono raggruppati, i parametri documentati, gli schema espandibili. È la stessa esperienza che otterresti da uno strumento dedicato di documentazione API, incorporata direttamente nel tuo workspace architetturale.

gRPC / Protocol Buffers — Incolla o sincronizza le tue definizioni .proto. Il visualizzatore renderizza servizi, metodi, tipi di messaggio ed enum con evidenziazione della sintassi e indentazione corretta. Basta cercare nei file proto per capire cosa espone un servizio.

GraphQL — Importa il tuo schema ed esplora tipi, query, mutation e subscription. E se hai configurato endpoint del server, ottieni un playground GraphiQL completo — scrivi query, eseguile contro la tua API reale ed esplora lo schema interattivamente, tutto senza lasciare Archyl.

AsyncAPI — Definisci le tue API event-driven con specifiche AsyncAPI. Il visualizzatore renderizza canali, operazioni, schema dei messaggi e binding del server con evidenziazione completa della sintassi. Che tu stia usando Kafka, RabbitMQ, NATS o WebSocket, i contratti AsyncAPI documentano quali eventi i tuoi servizi producono e consumano.

Importa da Git o Incolla Direttamente

Le specifiche API cambiano. Un endpoint viene aggiunto, un campo viene deprecato, una nuova versione viene rilasciata. Se la tua documentazione richiede copia-incolla manuale per restare aggiornata, non resterà aggiornata.

Per questo i Contratti API supportano due modalità di origine:

Sincronizzazione Git collega il tuo contratto a un file di specifica in un repository. Puntalo al tuo openapi.yaml, al tuo service.proto, al tuo schema.graphql o al tuo asyncapi.yaml, e Archyl recupera il contenuto direttamente. Quando la specifica cambia a monte, clicca sincronizza e il contratto si aggiorna. Funziona con ogni provider git supportato da Archyl — GitHub, GitLab, Bitbucket, Azure DevOps e istanze self-hosted.

Manuale è per i team che non tengono le specifiche in git, o per la prototipazione rapida. Incolla il contenuto della specifica direttamente e modificalo sul posto. Utile per abbozzare un contratto prima che il servizio esista, o per importare una specifica da un'API di terze parti che non controlli.

Entrambe le modalità supportano il versioning, così puoi tracciare quale versione del contratto stai documentando.

Collegato alla Tua Architettura

Ecco dove i Contratti API diventano più di un visualizzatore di specifiche.

Ogni contratto può essere collegato a uno o più elementi C4 — sistemi, container, componenti o elementi di codice. Una specifica OpenAPI può essere collegata al container API Gateway che la serve. Un proto gRPC può essere collegato al componente microservizio che lo implementa. Uno schema GraphQL può essere collegato al BFF (Backend for Frontend) che lo espone.

Questi link sono bidirezionali. Dal contratto, vedi quali elementi architetturali si relazionano ad esso. Dal pannello dettagli dell'elemento sul diagramma, vedi quali contratti descrivono la sua superficie API. Quando fai clic destro su un container nel canvas, puoi collegare e scollegare contratti direttamente dal menu contestuale.

Questo colma il divario che ho descritto all'inizio. Quando qualcuno chiede "com'è fatta l'API tra questi due servizi?", la risposta è a un clic di distanza. Non in uno strumento diverso, non in un repo diverso — proprio li sul diagramma.

Canali di Eventi

Le architetture event-driven sono notoriamente difficili da documentare. Quale servizio pubblica su quale topic? Qual è lo schema del messaggio? Chi lo consuma?

I Canali di Eventi di Archyl portano visibilità alla comunicazione asincrona. Ogni contratto AsyncAPI espone automaticamente i canali che definisce — topic, code, stream — e li mappa sugli elementi C4 che producono e consumano eventi.

Sul diagramma, i canali di eventi appaiono come tipi di connessione distinti, rendendo immediatamente chiaro quali relazioni sono chiamate API sincrone e quali sono flussi di eventi asincroni. Questo è critico per capire il comportamento del sistema: una chiamata REST tra due servizi ha caratteristiche di affidabilità e accoppiamento molto diverse da un evento pubblicato su un message broker.

Puoi anche creare canali di eventi indipendentemente dai contratti AsyncAPI, utile per documentare sistemi di messaggistica legacy o protocolli proprietari che non hanno una specifica formale.

Visualizzatori Interattivi

Non volevamo che i contratti fossero blocchi di testo grezzo. Ogni protocollo ottiene un visualizzatore costruito appositamente:

Il visualizzatore OpenAPI renderizza un riferimento API completamente interattivo. Gli endpoint sono organizzati per tag, con schema di richiesta/risposta espandibili, documentazione dei parametri e dettagli di autenticazione. Se hai definito URL del server, il visualizzatore li mostra così gli sviluppatori sanno dove inviare le richieste. È un'esperienza reale di documentazione API, non un dump YAML con evidenziazione della sintassi.

Il visualizzatore Protocol Buffer renderizza le definizioni proto con colorazione della sintassi appropriata, rendendo servizi, RPC e strutture dei messaggi facili da scansionare.

Il visualizzatore GraphQL evidenzia tipi, campi e direttive. E quando hai configurato un endpoint del server, una seconda scheda apre un playground GraphiQL completo. Puoi scrivere ed eseguire query contro la tua API live, esplorare lo schema tramite introspezione e testare mutation — tutto incorporato in Archyl. Se la tua API GraphQL ha più ambienti (staging, produzione), puoi definire più voci server e alternare tra di essi.

Il visualizzatore AsyncAPI renderizza le definizioni delle tue API event-driven con elenchi di canali, schema dei messaggi e configurazioni server/broker. Ogni canale mostra le sue operazioni (pubblica/sottoscrivi), schema del payload e binding — dando agli sviluppatori un quadro chiaro della tua superficie di comunicazione event-driven.

Come Iniziare

Naviga in qualsiasi progetto e apri la sezione Contratti API dalla sidebar. Clicca "Aggiungi Contratto" e scegli il tipo di protocollo e la modalità di origine.

Per i contratti da git, collega un repository (o riutilizzane uno già collegato al tuo progetto), specifica il percorso del file e il branch, e Archyl recupera la specifica. Per i contratti manuali, incolla il contenuto direttamente.

Una volta creato, vai al diagramma e collega il contratto agli elementi C4 rilevanti. Da quel punto in poi, chiunque esplori l'architettura può approfondire la superficie API effettiva dal diagramma stesso.

Perché Questo è Importante

I diagrammi architetturali sono potenti per mostrare la struttura — cosa esiste e come le cose si connettono. Ma sono sempre stati deboli sulle interfacce. Una freccia di relazione etichettata "REST/HTTPS" dice quasi nulla su cosa fluisce effettivamente tra due servizi. Un evento pubblicato su un topic Kafka è ancora più opaco — a meno che tu non abbia la specifica AsyncAPI e il mapping dei canali proprio li.

I contratti API colmano quel divario. Aggiungono precisione alle frecce. Quando un nuovo membro del team guarda la tua architettura e vede una connessione tra l'App Mobile e l'API Gateway, può immediatamente aprire la specifica OpenAPI e capire esattamente quali endpoint sono disponibili, quali strutture dati vengono scambiate e quale autenticazione e richiesta.

Questa e documentazione architetturale che si guadagna il suo spazio. Non perché qualcuno l'ha imposta, ma perché risponde a domande reali che emergono ogni giorno.

Stai già usando Archyl per la tua architettura? Esplora la funzionalità Contratti API nel tuo progetto. Nuovo sulla piattaforma? Scopri il modello C4 e come la scoperta con IA può generare automaticamente il tuo diagramma architetturale.