Affinché l'API sia facile da comprendere, implementare e supportare, la documentazione di qualità è importante. Configuriamo la generazione automatica di documentazione basata su specifiche OpenAPI con Swagger UI e Redoc, i due strumenti di visualizzazione API più popolari.
In questo modo è possibile fornire agli sviluppatori un'interfaccia interattiva in cui è possibile esaminare la struttura dei metodi, testare le richieste e connettersi rapidamente all'API.
Cosa include nella documentazione
| Sezione | Descrizione |
|---|---|
| Endpoint's e metodi | Elenco completo percorsi, metodi HTTP, parametri, intestazioni |
| Esempi di richieste/risposte | Script per curl, postman, JavaScript, python e altre lingue |
| Autorizzazione | Supporto per JWT, OAuth2, API Key direttamente dall'interfaccia |
| Diagrammi di oggetti | Descrizione dei modelli, delle strutture nidificate e dei requisiti di dati |
| Codici di errore | Tutti gli stati possibili con spiegazioni |
Strumenti che usiamo
Documentazione interattiva Swagger UI nel browser, testabile
Redoc - interfaccia leggibile, statica, ideale per la pubblicazione sul sito
OpenAPI 3. 0/3. 1 è il formato della specifica su cui si basa tutto
Generazione automatica da codice - Annotazione, descrizione, versione e aggiornamento automatico della documentazione
Esportazione in JSON/YAML/HTML
Vantaggi per team e partner
Accelerazione della gestione dei nuovi sviluppatori
Riduzione degli errori di integrazione
Documentazione sempre aggiornata e sincronizzata con il codice
Avvio rapido dell'integrazione senza supporto tecnico
Facile da pubblicare su portali pubblici o privati
Dove è particolarmente importante
API aperte per sviluppatori esterni
API interne con sviluppo attivo
Piattaforme con integrazioni B2B e SDK
Servizi che richiedono la regolamentazione e la convalida degli schemi
Swagger e Redoc sono gli standard API di nuova generazione. Configureremo la generazione, l'aggiornamento e la pubblicazione della documentazione in modo che ogni sviluppatore possa iniziare l'integrazione con l'API in pochi minuti.