Creare la documentazione relativa all'API
Documentare l'API di un repository di codice sorgente è essenziale per fornire chiarezza, accessibilità e facilità d'uso per gli sviluppatori che gestiscono e utilizzano l'API. La documentazione completa funge da guida per comprendere le funzionalità, gli input, gli output e l'utilizzo degli endpoint API. Quando si documenta l'API, è consigliabile selezionare il formato di presentazione più adatto (ad esempio, la specifica OpenAPI o Markdown), inclusi esempi e scenari di utilizzo, mantenerlo aggiornato con le modifiche al codice e richiedere feedback dai consumer dell'API, in modo da migliorarne continuamente la qualità.
Anche se l'approccio generale alla documentazione dell'API è indipendente dalla piattaforma, esistono alcune differenze a livello di implementazione tra Azure DevOps e GitHub.
Documentazione dell'API in Azure DevOps
Per aggiungere la documentazione dell'API a un progetto Azure DevOps nel modo più efficiente, è consigliabile utilizzare uno strumento di documentazione o una piattaforma dedicata, che si integri con il flusso di lavoro di sviluppo. Le scelte più comuni in questa categoria includono Swagger (OpenAPI), API Blueprint e sistemi di documentazione basati su Markdown, come MkDocs o Docusaurus. Le funzionalità di integrazione di Azure DevOps consentono di automatizzare il processo di generazione della documentazione, mantenendola sincronizzata con la codebase. La maggior parte degli strumenti di documentazione supporta anche l'analisi dei commenti inline, includendoli nella documentazione generata automaticamente.
È consigliabile pubblicare la documentazione dell'API in una posizione centrale, accessibile ai membri del team e agli stakeholder. Potrebbe trattarsi di un sito Web dedicato per la documentazione, un wiki all'interno di Azure DevOps o un portale di documentazione esterno.
In alternativa, è possibile ricorrere ad annotazioni di codice o a elementi Decorator posti direttamente all'interno del codice, così da aggiungere metadati che ne descrivono gli endpoint API. Gli strumenti come Swagger Codegen o Springfox sono in grado di elaborare tali annotazioni e generare i file di specifica OpenAPI.
Ogni volta che viene apportata una modifica alla codebase, configurare processi automatizzati all'interno di Azure Pipelines, in modo da generare automaticamente la documentazione dell'API. Ciò garantisce che la documentazione rimanga aggiornata e rifletta le modifiche più recenti nelle API.
Documentare l'API in Github
Quando si utilizza GitHub, è consigliabile generare la documentazione dell'API sfruttando gli strumenti che fanno parte dell'ecosistema GitHub.
Per iniziare, documentare gli endpoint API, le operazioni, i parametri, le risposte e qualsiasi altra informazione pertinente. Prendere in considerazione la creazione di tale documentazione nel formato Markdown per tenere conto del supporto generale e della facilità d'uso. Definire una struttura coerente di singoli documenti, dividendo ciascuno in sezioni che descrivono l'autenticazione, gli endpoint, i parametri di richiesta, gli esempi di risposta e così via.
Come avviene con Azure DevOps, per semplificare il processo di generazione della documentazione dell'API dai file Markdown è possibile usare generatori di documentazione o generatori di siti statici. Le scelte più comuni includono Jekyll, MkDocs, Docusaurus e Hugo. Configurare il generatore per analizzare i file Markdown e generare pagine HTML statiche. È possibile personalizzare il layout, il tema e lo stile, in modo che corrispondano alle preferenze e alla personalizzazione del progetto.
Per pubblicare il contenuto HTML, sfruttare GitHub Pages, che consente di ospitare siti Web statici direttamente dal repository GitHub. A questo scopo, è possibile creare un ramo dedicato ed eseguirvi il push dei file HTML. È anche possibile implementare GitHub Actions per compilare e distribuire automaticamente la documentazione dell'API, ogni volta che viene apportata una modifica ai file di documentazione o alla codebase.
Configurare GitHub Actions per compilare e distribuire automaticamente la documentazione dell'API, ogni volta che viene apportata una modifica ai file di documentazione o alla codebase. Configurare il flusso di lavoro di automazione per generare i file di documentazione HTML usando il generatore di documentazione scelto e distribuirli in GitHub Pages.