Creare la documentazione dell'API
Documentare l'API di un repository di codice sorgente è essenziale per fornire chiarezza, accessibilità e facilità d'uso per gli sviluppatori che mantengono e usano 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, specifica OpenAPI o Markdown), inclusi esempi e scenari di utilizzo, mantenerlo up-to-date con modifiche al codice e richiedere feedback dai consumer dell'API per migliorarne continuamente la qualità.
Anche se l'approccio generale alla documentazione dell'API è indipendente dalla piattaforma, esistono alcune differenze nell'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 usare uno strumento di documentazione o una piattaforma dedicata che si integra 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, mantenendolo sincronizzato con la codebase. La maggior parte degli strumenti di documentazione supporta anche l'analisi dei commenti inline e includerli 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 usare annotazioni di codice o elementi Decorator direttamente all'interno del codice per aggiungere metadati che ne descrivono gli endpoint API. Gli strumenti come Swagger Codegen o Springfox sono in grado di elaborare queste annotazioni e generare i file di specifica OpenAPI.
Configurare processi automatizzati all'interno di Azure Pipelines per generare automaticamente la documentazione dell'API ogni volta che viene apportata una modifica alla codebase. Ciò garantisce che la documentazione rimanga up-to-date e rifletta le modifiche più recenti nelle API.
Documentare l'API in Github
Quando si usa 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 ogni 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 generazione della documentazione dell'API dai file Markdown. Le scelte più popolari 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 eseguire il push dei file HTML in questo ramo. È 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.