Creare la documentazione dell'API
La creazione della documentazione dell'API per il repository del codice sorgente è molto importante. Una buona documentazione consente agli sviluppatori di comprendere, gestire e usare facilmente l'API. La documentazione completa illustra il funzionamento dell'API, gli input necessari, gli output che fornisce e come usare gli endpoint API. Quando si crea la documentazione dell'API, è consigliabile scegliere il formato migliore (ad esempio, specifica OpenAPI o Markdown), includere esempi e scenari di utilizzo, mantenerlo aggiornato quando il codice cambia e chiedere agli utenti dell'API di fornire commenti e suggerimenti per migliorarlo. Anche se l'approccio generale alla documentazione dell'API funziona ovunque, esistono alcune differenze tra Azure DevOps e GitHub.
Creazione della documentazione dell'API in Azure DevOps
Per aggiungere la documentazione dell'API a un progetto Azure DevOps in modo efficiente, è consigliabile usare uno strumento di documentazione dedicato che funziona con il flusso di lavoro di sviluppo. Le scelte più comuni includono Swagger (OpenAPI), Api Blueprint e sistemi di documentazione basati su Markdown come MkDocs o Docusaurus. L'integrazione di Azure DevOps consente di automatizzare la creazione della documentazione e di mantenere la sincronizzazione con il codice. La maggior parte degli strumenti di documentazione può anche leggere commenti inline e includerli nella documentazione generata automaticamente.
È consigliabile pubblicare la documentazione dell'API in una posizione centrale a cui possono accedere i membri del team e gli stakeholder. Potrebbe trattarsi di un sito Web dedicato per la documentazione, un wiki all'interno di Azure DevOps o un portale di documentazione esterno.
È anche possibile usare annotazioni di codice o elementi decoratori direttamente nel codice per aggiungere metadati che descrivono gli endpoint API. Gli strumenti come Swagger Codegen o Springfox possono elaborare queste annotazioni e creare file di specifica OpenAPI.
Configurare processi automatizzati all'interno di Azure Pipelines per creare automaticamente la documentazione dell'API ogni volta che viene apportata una modifica al codice. Ciò garantisce che la documentazione rimanga aggiornata e rifletta le modifiche più recenti nelle API.
Creazione della documentazione dell'API in GitHub
Quando si usa GitHub, è consigliabile creare la documentazione dell'API usando 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 in formato Markdown perché è ampiamente supportata e facile da usare. Definire una struttura coerente per singoli documenti, suddividendoli in sezioni che descrivono l'autenticazione, gli endpoint, i parametri di richiesta, gli esempi di risposta e così via.
Come con Azure DevOps, è possibile usare generatori di documentazione o generatori di siti statici per semplificare il processo di creazione della documentazione dell'API dai file Markdown. Le scelte più popolari includono Jekyll, MkDocs, Docusaurus e Hugo. Configurare il generatore per leggere i file Markdown e creare 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, usare GitHub Pages, che consente di ospitare siti Web statici direttamente dal repository GitHub. A questo scopo, è possibile creare un ramo dedicato ed eseguire il push dei file HTML in questo ramo. È anche possibile usare GitHub Actions per compilare e distribuire automaticamente la documentazione dell'API ogni volta che viene apportata una modifica ai file di documentazione o al codice.
Configurare GitHub Actions per compilare e distribuire automaticamente la documentazione dell'API ogni volta che viene apportata una modifica ai file di documentazione o al codice. Configurare il flusso di lavoro di automazione per creare i file di documentazione HTML usando il generatore di documentazione scelto e distribuirli in GitHub Pages.