Swagger – API Dokumentationen und Sandbox

Es gibt nette Programmier-Aufgaben, und es gibt nicht so nette. Hat man einmal ein Problem gelöst, und arbeitet nur noch an der Fertigstellung, dann ist der Spass wohl verflogen. Eine Dokumentation zu schreiben ist jedes mal aufs neue ein Kampf, aber auch ein notwendiges Übel. Undokumentierte Quelltexte gehen gar nicht! Zum einen muss man damit rechnen das auch mal jemand Drittes verstehen möchte, was da eigentlich passiert, zum anderen kann ich garantieren das man es spätestens nach 6 Monaten selbst auch nicht mehr weiss.

Screenshot von Swagger

Am wichtigsten ist eine Dokumentation jedoch genau dann, wenn man eine API implementiert hat, und das direkt aus mehreren Gründen:

  • Je genauer und besser die Dokumentation, desto weniger Rückfragen kommen
  • Sinn und Zweck einer API ist, das sie auch jemand benutzt => je besser dokumentiert, desto mehr Nutzer
  • Daraus lässt sich wieder der Erfolg eines Projektes ableiten, denn je mehr API-Nutzer, desto größer der Erfolg

Swagger stellt nun eine Möglichkeit bereit, APIs zu dokumentieren. Das sieht nicht nur hübsch aus, sondern funktioniert auch ziemlich einfach. Neben der klaren Strukturierung der dabei entstehenden Dokumentation, die nun wirklich jeder relativ einfach verstehen sollte, bietet Swagger einen interessanten Mehrwert: eine Sandbox! Will heissen das man die entsprechende Funktion in der Doku einfach aufklappt, und Swagger aus den notwendigen Parametern ein Formular zusammen bastelt. Hier kann man direkt Demo-Daten eintragen und sich das von der API gelieferte Ergebnis direkt anschauen.

Ob man Swagger benutzt bleibt jedem selbst überlassen, aber die Demo-Dokumentationen sind gute Beispiele dafür, wie man eine API-Dokumentation aufbauen könnte, plus dem wirklich sinnvollen Mehrwert der Sandbox. Also einfach mal schauen und vielleicht beim nächsten Projekt beherzigen!

 

Ähnliche Beiträge

Tutorial zur Entwicklung von REST-APIs REST (Representational State Transfer) bezeichnet einen Softwarearchitekturstil. Grundlegend bezeichnet REST heutzutage eine einfache Schnittstelle, d...
Google Analytics GA.PI() – Klasse um Analytics mit... Dass Google Analytics eine API anbietet, um direkt Daten auszulesen und diese selbst darzustellen ist nichts Neues. Wie bei allen APIs stellt sich abe...
Amazon Product Advertising API – Änderung de... Da mich Amazon inzwischen im spamverdächtigen Bereich mit E-Mail penetriert hier noch mal der Hinweis das ihr die Authentifizierung in euren Altanwend...
CSS3-Selektoren für JSON JSON ist eine feine Sache und aus der heutigen Webentwicklung fast nicht mehr wegzudenken. Benutzt man allerdings Vanilla Javascript und keine Bibliot...

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.