API-documentatie maken
Het documenteren van de API van een opslagplaats met broncode is essentieel voor het bieden van duidelijkheid, toegankelijkheid en gebruiksgemak voor ontwikkelaars die de API onderhouden en gebruiken. Uitgebreide documentatie fungeert als richtlijn voor het begrijpen van de functionaliteit, invoer, uitvoer en gebruik van de API-eindpunten. Wanneer u de API documenteert, moet u de meest geschikte presentatie-indeling (zoals OpenAPI-specificatie of Markdown) selecteren, inclusief voorbeelden en gebruiksscenario's, deze up-to-date houden met codewijzigingen en feedback vragen van API-consumenten om de kwaliteit ervan voortdurend te verbeteren.
Hoewel de algemene benadering voor het documenteren van API platformneutraal is, zijn er enkele verschillen in de implementatie tussen Azure DevOps en GitHub.
Api documenteren in Azure DevOps
Als u API-documentatie wilt toevoegen aan een Azure DevOps-project op de meest efficiënte manier, moet u overwegen een speciaal documentatiehulpprogramma of -platform te gebruiken dat kan worden geïntegreerd met uw ontwikkelwerkstroom. Populaire opties in deze categorie zijn onder andere Swagger (OpenAPI), API Blueprint en op Markdown gebaseerde documentatiesystemen zoals MkDocs of Docusaurus. Dankzij de integratiemogelijkheden van Azure DevOps kunt u het proces van het genereren van documentatie automatiseren, zodat deze gesynchroniseerd blijft met de codebasis. De meeste documentatiehulpprogramma's ondersteunen ook het parseren van inlineopmerkingen en het opnemen ervan in de automatisch gegenereerde documentatie.
U moet de API-documentatie publiceren naar een centrale locatie die toegankelijk is voor uw teamleden en belanghebbenden. 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 de API-eindpunten beschrijven. Hulpprogramma's zoals Swagger Codegen of Springfox kunnen deze aantekeningen verwerken en de OpenAPI-specificatiebestanden genereren.
Stel geautomatiseerde processen in uw Azure Pipelines in om automatisch API-documentatie te genereren wanneer er een wijziging in de codebasis is. Dit zorgt ervoor dat uw documentatie up-to-date blijft en de meest recente wijzigingen in uw API's weergeeft.
Api documenteren in Github
Wanneer u GitHub gebruikt, kunt u OVERWEGEN API-documentatie te genereren door gebruik te maken 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 in de Markdown-indeling te maken om rekening te houden met de brede ondersteuning en het gebruiksgemak ervan. Definieer een consistente structuur van 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 genereren van API-documentatie vanuit Markdown-bestanden te stroomlijnen. Populaire opties zijn Onder andere Jekyll, MkDocs, Docusaurus en Hugo. Configureer de generator om Markdown-bestanden te parseren en statische HTML-pagina's te genereren. 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, maakt u gebruik van 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 implementeren om uw API-documentatie automatisch te bouwen en te implementeren wanneer er een wijziging is in de documentatiebestanden of de codebasis.
Stel GitHub Actions in om uw API-documentatie automatisch te bouwen en te implementeren wanneer er een wijziging is in de documentatiebestanden of de codebasis. Configureer de automatiseringswerkstroom voor het genereren van de HTML-documentatiebestanden met behulp van de gekozen documentatiegenerator en implementeer deze in GitHub Pages.