Skapa API-dokumentation
Det är viktigt att dokumentera API:et för en källkodslagringsplats för att tillhandahålla klarhet, tillgänglighet och användarvänlighet för utvecklare som underhåller och använder API:et. Omfattande dokumentation fungerar som en guide för att förstå funktionerna, indata, utdata och användningen av API-slutpunkterna. När du dokumenterar API:et bör du välja det lämpligaste presentationsformatet (till exempel OpenAPI-specifikation eller Markdown), inklusive exempel och användningsscenarier, hålla det uppdaterat med kodändringar och begära feedback från API-konsumenter för att kontinuerligt förbättra dess kvalitet.
Den allmänna metoden för att dokumentera API är plattformsoberoende, men det finns vissa skillnader i implementeringen mellan Azure DevOps och GitHub.
Dokumentera API i Azure DevOps
Om du vill lägga till API-dokumentation i ett Azure DevOps-projekt på det mest effektiva sättet bör du överväga att använda ett dedikerat dokumentationsverktyg eller en plattform som integreras med ditt arbetsflöde för utveckling. Populära alternativ i den här kategorin är Swagger (OpenAPI), API Blueprint och Markdown-baserade dokumentationssystem som MkDocs eller Docusaurus. Deras Azure DevOps-integreringsfunktioner hjälper till att automatisera processen för generationsdokumentation och hålla den synkroniserad med kodbasen. De flesta dokumentationsverktyg stöder också parsning av infogade kommentarer och inkluderar dem i den automatiskt genererade dokumentationen.
Du bör publicera API-dokumentationen på en central plats som är tillgänglig för dina teammedlemmar och intressenter. Det kan vara en dedikerad dokumentationswebbplats, en wiki i Azure DevOps eller en extern dokumentationsportal.
Du kan också använda kodanteckningar eller dekoratörer direkt i koden för att lägga till metadata som beskriver dess API-slutpunkter. Verktyg som Swagger Codegen eller Springfox kan bearbeta dessa anteckningar och generera OpenAPI-specifikationsfilerna.
Konfigurera automatiserade processer i dina Azure Pipelines för att generera API-dokumentation automatiskt när det sker en ändring i kodbasen. Detta säkerställer att dokumentationen förblir uppdaterad och återspeglar de senaste ändringarna i dina API:er.
Dokumentera API i Github
När du använder GitHub bör du överväga att generera API-dokumentation genom att använda verktyg som ingår i GitHub-ekosystemet.
Börja med att dokumentera dina API-slutpunkter, åtgärder, parametrar, svar och annan relevant information. Överväg att skapa den dokumentationen i Markdown-format för att ta hänsyn till dess breda support och användarvänlighet. Definiera en konsekvent struktur för enskilda dokument, dela upp var och en i avsnitt som beskriver autentisering, slutpunkter, parametrar för begäran, svarsexempel osv.
Precis som med Azure DevOps kan du använda dokumentationsgeneratorer eller statiska platsgeneratorer för att effektivisera processen med att generera API-dokumentation från Markdown-filer. Populära alternativ är Jekyll, MkDocs, Docusaurus och Hugo. Konfigurera generatorn för att parsa Markdown-filer och generera statiska HTML-sidor. Du kan anpassa layouten, temat och formateringen så att de matchar projektets varumärkesanpassning och inställningar.
Om du vill publicera HTML-innehållet använder du GitHub Pages, som gör att du kan vara värd för statiska webbplatser direkt från din GitHub-lagringsplats. För det här ändamålet kan du skapa en dedikerad gren och skicka HTML-filerna till den här grenen. Du kan också implementera GitHub Actions för att automatiskt skapa och distribuera DIN API-dokumentation när det sker en ändring i dokumentationsfilerna eller kodbasen.
Konfigurera GitHub Actions för att automatiskt skapa och distribuera DIN API-dokumentation när det sker en ändring i dokumentationsfilerna eller kodbasen. Konfigurera arbetsflödet för automatisering för att generera HTML-dokumentationsfilerna med hjälp av den valda dokumentationsgeneratorn och distribuera dem till GitHub Pages.