API-documentatie maken

Het maken van API-documentatie voor uw opslagplaats voor broncode is erg belangrijk. Goede documentatie helpt ontwikkelaars om uw API eenvoudig te begrijpen, te onderhouden en te gebruiken. In de volledige documentatie wordt uitgelegd hoe de API werkt, welke invoer deze nodig heeft, welke uitvoer het geeft en hoe u de API-eindpunten gebruikt. Wanneer u API-documentatie maakt, moet u de beste indeling kiezen (zoals OpenAPI-specificatie of Markdown), voorbeelden en gebruiksscenario's opnemen, deze bijwerken wanneer code wordt gewijzigd en API-gebruikers vragen om feedback om deze beter te maken. Hoewel de algemene benadering van API-documentatie overal werkt, zijn er enkele verschillen tussen Azure DevOps en GitHub.

API-documentatie maken in Azure DevOps

Als u API-documentatie efficiënt wilt toevoegen aan een Azure DevOps-project, moet u een speciaal documentatiehulpprogramma gebruiken dat werkt met uw ontwikkelwerkstroom. Populaire opties zijn onder andere Swagger (OpenAPI), API Blueprint en op Markdown gebaseerde documentatiesystemen zoals MkDocs of Docusaurus. Hun Azure DevOps-integratie helpt het maken van documentatie te automatiseren en deze gesynchroniseerd te houden met uw code. De meeste documentatiehulpprogramma's kunnen ook inlineopmerkingen lezen en opnemen in automatisch gegenereerde documentatie.

U moet de API-documentatie publiceren op een centrale locatie waartoe uw teamleden en belanghebbenden toegang hebben. Dit kan een speciale documentatiewebsite, een wiki binnen Azure DevOps of een externe documentatieportal zijn.

U kunt ook codeaantekeningen of decorators rechtstreeks in uw code gebruiken om metagegevens toe te voegen die uw API-eindpunten beschrijven. Hulpprogramma's zoals Swagger Codegen of Springfox kunnen deze aantekeningen verwerken en OpenAPI-specificatiebestanden maken.

Stel geautomatiseerde processen in uw Azure Pipelines in om automatisch API-documentatie te maken wanneer er een wijziging in de code is. Dit zorgt ervoor dat uw documentatie actueel blijft en de meest recente wijzigingen in uw API's weergeeft.

API-documentatie maken in GitHub

Wanneer u GitHub gebruikt, kunt u overwegen API-documentatie te maken met behulp van hulpprogramma's die deel uitmaken van het GitHub-ecosysteem.

Begin met het documenteren van uw API-eindpunten, bewerkingen, parameters, antwoorden en andere relevante informatie. Overweeg om die documentatie te maken in Markdown-indeling, omdat deze algemeen wordt ondersteund en eenvoudig te gebruiken. Definieer een consistente structuur voor afzonderlijke documenten, waarbij elk document wordt verdeeld in secties waarin verificatie, eindpunten, aanvraagparameters, antwoordvoorbeelden, enzovoort worden beschreven.

Net als bij Azure DevOps kunt u documentatiegeneratoren of statische sitegeneratoren gebruiken om het proces van het maken van API-documentatie vanuit Markdown-bestanden eenvoudiger te maken. Populaire opties zijn Onder andere Jekyll, MkDocs, Docusaurus en Hugo. Stel de generator in om Markdown-bestanden te lezen en statische HTML-pagina's te maken. U kunt de indeling, het thema en de stijl aanpassen aan de huisstijl en voorkeuren van uw project.

Als u de HTML-inhoud wilt publiceren, gebruikt u GitHub Pages, waarmee u statische websites rechtstreeks vanuit uw GitHub-opslagplaats kunt hosten. U kunt hiervoor een toegewezen vertakking maken en de HTML-bestanden naar deze vertakking pushen. U kunt gitHub Actions ook gebruiken om uw API-documentatie automatisch te bouwen en te implementeren wanneer er een wijziging is in de documentatiebestanden of de code.

Stel GitHub Actions in om uw API-documentatie automatisch te bouwen en te implementeren wanneer er een wijziging is in de documentatiebestanden of de code. Configureer de automatiseringswerkstroom om de HTML-documentatiebestanden te maken met behulp van de door u gekozen documentatiegenerator en implementeer deze in GitHub Pages.