Schnittstellen Dokumentation

Dokumentation der Schnittstellen

prahlerisch sein Vielleicht noch wichtiger als die Dokumentation des Quellcodes für Wartungs- und Ergänzungszwecke ist die Dokumentation der Schnittstellen, über die auf das Software-System zugegriffen werden kann. Für die Nutzung einer solchen Schnittstelle ist es erforderlich, den Aufbau und die gebotenen Funktionalitäten zu verstehen. Eine gemeinsame Programmiersprache für die Erstellung dieser Programmierschnittstellen ist der Repräsentational State Transfer (REST).

Zahlreiche Websites nutzen wiederherstellbare APIs, darunter Amazon, Google, LinkedIn und P2. Um sicherzustellen, dass die Interface-Dokumentation so nah wie möglich an der Implementation ist, ermöglicht Switch die Platzierung der notwendigen Daten auf dem Java-Code. Von nun an beschreibt sich die Interface-Dokumentation selbst. Für jede Benutzeroberfläche können alle notwendigen Daten gespeichert und die Benutzeroberfläche über die zugehörigen Swagger-Anmerkungen erfasst werden.

Diese Dokumentation kann dann über Annotationen in den Java-Klassen abgelegt werden.

GitHub stellt das umfassende System auf GitHub auch Swagger-Implementierungen für andere Programmierungssprachen zur Verfügung. Host-Name und Basis-Pfad sind nicht obligatorisch. Ein Beispiel ist die API der Datenübertragungslösung calvaDrive, die ebenso mit der Firma Schwagger beschrieben wurde. Die folgende Grafik zeigt die Swagger-Dokumentation der GET-Methode der REST-Ressource'settings'.

Dazu gehören eine generelle Erläuterung der Methodik und eventuell zurückgesendete HTTP-Statuscodes mit ihren jeweiligen Beschreibungen. Es bildet auch den Rückgabedatentyp, in diesem Falle JSON, und die Beschaffenheit des von der REST-Ressource zurückgegebenen Settings-Objekts ab. Allerdings muss es Schnittstellen zum Datenaustausch bereitstellen. In einem Software-System gibt es einen Mikroservice für die Suche und einen für den Auftrag, diese Bausteine müssen in der Lage sein, über eine Oberfläche in der Lage zu sein, Information weiterzugeben.

Wenn zwei fest miteinander verbundene Bauteile von zwei unterschiedlichen Arbeitsgruppen gemeinsam erarbeitet werden, sind Vereinbarungen über die Wirkstoffe erforderlich, was die Entwicklungsgeschwindigkeit verringert. 10 ]Eine qualitativ hochwertige Interface-Dokumentation bringt gerade im Mikro-Service-Umfeld große Vorzüge. Für die öffentlichen und internen Schnittstellen ist eine nachvollziehbare Dokumentation von entscheidender Bedeutung für die Entwickler, um sie nutzen zu können.

Insbesondere für verteilte Arbeitsgruppen ist die Dokumentation von unternehmensinternen Schnittstellen sehr bedeutsam. Im Falle von öffentlich zugänglichen Wirkstoffen ist die Dokumentation für deren Weitergabe und damit für die Konkurrenzfähigkeit ausschlaggebend. Mit Hilfe von Swager kann die Dokumentation der REST-Schnittstellen unmittelbar auf dem Programmcode gespeichert und weitestgehend automatisch generiert werden. Dies ist ein entscheidendes Plus, denn die Schnittstellendokumentation ist zwar von Bedeutung, erfordert aber immer Zeit und damit ein günstiges Kosten-Nutzen-Verhältnis.

Dadurch wird auch gewährleistet, dass die Dokumentation mit dem weiterentwickelten Messsystem gleichmässig mitwächst und bei Veränderungen anpaßt.

Mehr zum Thema