API documentation
Misschien vraag je jezelf af wat API-documentatie is en waarom we het nodig hebben.
Application Programming Interface (API) is een software-intermediair, die de mogelijkheid biedt dat twee applicaties met elkaar kunnen praten. 'Application' kan verwijzen naar bepaalde software, terwijl het woord 'Interface' kan worden gezien als een contract of service tussen twee applicaties.
In niet-technische termen, is een API de boodschapper die jouw vraag aan je vriend bezorgt en terugkeert met het antwoord.
Laten we eens uitgaan van een hypothese: Jouw vrienden zijn computers en wat je van hen weet is API-documentatie.
Je hebt twee vrienden. Bert is wiskundeleraar. En je andere vriend heet Tim. Tim heeft familie in Duitsland, met wie hij Duits spreekt.
Je bent op je werk bezig met het maken van een e-mail aan een Duitssprekende klant. Het kost je nogal wat tijd om deze e-mail te schrijven en je zou graag willen dat iemand naar de mail kijkt en hem corrigeert als dat nodig is. Deze e-mail moet zo snel mogelijk worden verzonden.
Zonder deze API-documentatie:
Zou je geen van je twee vrienden om hulp kunnen vragen en zou je nog veel langer met dit probleem worstelen.
Zou je deze e-mail misschien wel verzenden, maar met nog een heleboel fouten erin.
Met API-documentatie:
Kun je zien dat Bert jouw vraag (of verzoek) niet kan beantwoorden, maar Tim wel. Weet je nu naar WIE je moet gaan en HOE je het moet vragen. Je mail wordt gecorrigeerd en zonder problemen of stress verstuurd.
Zoals we allebei kunnen zien, kan API-documentatie je veel tijd besparen.
Swagger
Wat is Swagger? Swagger is een technologie, waarmee je jouw API-structuur kunt beschrijven en lezen. Hiermee kunnen we voor elke API interactieve API-documentatie bouwen. Swagger kan een serverstub, clientbibliotheken en interactieve API-documentatie genereren. In dit artikel zullen we dieper ingaan op Swagger UI die verantwoordelijk is voor API-documentatie.
Deze gegenereerde documentatie ziet er een beetje zo uit:
De algemene opzet van deze pakketten is gemakkelijk te volgen en neemt niet al te veel tijd in beslag. Het zijn de annotaties die het grootste deel van je tijd in beslag nemen als je de volledige documentatie wilt (parameters, antwoorden, enz.).
Op dit moment is het het beste te integreren met Microsoft.
Manual
Door handmatig annotaties te schrijven voor je endpoints, genereer je de nodige informatie voor Swagger. Hiermee kan Swagger een JSON- of YAML-bestand genereren dat gebruikt kan worden om een interactieve frontend-pagina te genereren die jouw API-documentatie weergeeft.
Als programmeurs zijn we vaak geen fan van handmatig werk. Hoewel veel frameworks op een schone manier interageren met Swagger, zijn er nog steeds annotaties nodig binnen elk framework.
Deze annotatie ziet er in elk framework een beetje anders uit. In Laravel ziet het er als volgt uit:
Automatic
Er zijn ontwikkelaars, die gewerkt hebben aan pakketten die Swagger UI gebruiken op een manier waarbij je geen annotatie nodig hebt. Deze pakketten maken jouw endpoint-documentatie zonder annotatie. Voor parameters, reacties en meer in dept documentatie zul je echter moeten annoteren.
In .NET: Swashbuckle en NSwag.
Deze worden door Microsoft zelf aanbevolen om te gebruiken.
Laravel: DarkaOnLine
IBM: Swagger UI (meer hierover hieronder).
Knooppunt: Swagger-knooppunt
Laten we inzoomen op de automatisch gegenereerde code voor Laravel. Wat doet dit pakket? Dit pakket begint met jouw routing. Het zal jouw API-bestand gebruiken om elke route te doorlopen en goed te kijken naar de gekoppelde methode van de gekoppelde controller.
Dit zal een impact hebben bij het maken van routes met resource() of apiresource() commando waarbij niet elke route een methode of controller achter zich heeft. Dit dwingt je om uitsluitend URL-routes voor een bestaand endpoint te maken. Wat ik persoonlijk eerder een voordeel dan een nadeel vind.
Na gebruik van de route, zal het naar je methode gaan en zoeken naar annotaties voor parameters. Nadat dit voor elke route gedaan is, zal het je JSON-bestand met documentatie genereren.
IBM
IBM heeft geen automatisch pakket en heeft annotaties nodig. Bovendien heeft het een aantal beperkingen die voortkomen uit IBM zelf. Die kun je gemakkelijk vinden in de volgende link: https://www.ibm.com/docs/en/app-connect/11.0.0?topic=apis-restrictions-swagger-documents
API documentatie is altijd waardevol om te hebben. Zo kunnen andere teamleden gemakkelijk de endpoints in de documentatie van de API controleren voor een eenvoudigere samenwerking. (Zolang jij annotaties blijft schrijven bij het maken van nieuwe endpoints).
Ook al wordt het niet automatisch gegenereerd voor IBM, toch denk ik dat het de moeite waard is om deze of een andere technologie te gebruiken voor het documenteren van je API!
