Swagger API-documentatie tutorial voor beginners – Deel 1: Inleiding tot API-documentatie met Swagger

Wat is Swagger?

Het doel van Swagger™ is om een standaard te definieren voor taal-onafhankelijke REST API’s. Hiermee kunnen zowel mensen als computers de mogelijkheden van een dienst ontdekken en begrijpen, zonder toegang tot de broncode, documentatie of netwerkverkeer te hoeven inspecteren. Wanneer een API goed is gedocumenteerd met Swagger, kan een gebruiker met minimale code al begrijpen en met de service interacteren. Net zoals interfaces in lagere programmeertalen de complexiteit verminderen, elimineert Swagger de gokken bij het aanroepen van een service.

Technisch gezien is Swagger een formele specificatie met een groot ecosysteem aan tools, waaronder frontend-interfaces, low-level bibliotheken en commerciële API-management oplossingen.

Hoe begin je?

Als je een API-aanbieder bent en Swagger wilt gebruiken om je API’s te documenteren, zijn er verschillende benaderingen mogelijk:

Een *top-down* aanpak, waarbij je de Swagger Editor gebruikt om je Swagger-definitie te maken en vervolgens de geïntegreerde Swagger Codegen-tools om de serverimplementatie te genereren.
Als