© Excellent backgrounds/Shutterstock.com
Java Magazin
RESTful APIs dokumentieren

Eine gute Doku ist der Schlüssel

Der Begriff API-Economy taucht immer öfter auf und macht so deutlich, wie wichtig Web-APIs sind. Die Verbreitung und damit die Wettbewerbsfähigkeit eines Web-API steht und fällt mit einer guten Dokumentation. Denn sowohl öffentliche als auch interne APIs benötigen einen verständlichen Developer Guide, damit Entwickler sie einsetzen können. Mit den Open-Source-Projekten Swagger2Markup und AsciidoctorJ lässt sich ein Developer Guide erstellen, der sich mit handgeschriebener AsciiDoc-Dokumentation kombinieren lässt und sowohl offline als auch online lesbar ist.

Robert Winkler


In der letzten Zeit sind viele Spezifikationsformate und Frameworks entstanden, die Spezifikation und Dokumentation eines HTTP-basierten API vereinfachen und vereinheitlichen sollen. Zu den bekanntesten Spezifikationsformaten gehören Swagger (nun OpenAPI-Spezifikation [1]), RAML [2] oder API Blueprint [3]. All diese Projekte haben zum Ziel, ein Spezifikationsformat zu entwickeln, das zwar maschinenlesbar ist, aber mit dem in erster Linie Menschen arbeiten sollen. Sie nutzen hierfür unterschiedliche Formate wie JSON, YAML oder Markdown. Denn XML-basierte Formate wie die Web Application Description Language (WADL) eignen sich hierfür weniger. Diese Spezifikationsformate für sich alleine sind aber kein Developer Guide wie der GitHub API Developer Guide [4]. Developer Guides sollten weitere Informationen enthalten, wie ein Tutorial mit echten HTTP-Request- und -Response-Beispielen oder Codebeispiele und curl-Kommandos, mit denen sich das API testen lässt.

Swagger ist das momentan am weitesten verbreitete Spezifikationsformat für HTTP-basierte APIs. Um Swagger herum hat sich eine große Toollandschaft gebildet. Ein Beispiel ist die Onlinekollaborationsplattform SwaggerHub, die eine Zusammenarbeit an Swagger-Spezifikationen ermöglichen soll. SwaggerHub unterstützt den gesamten Lebenszyklus eines API und bietet hierfür einen Onlineeditor für das Erstellen einer Swagger-Spezifikation an sowie eine Integration mit GitHub, Versionisierung und Codegenerierung. Ursprünglich war Swagger in der Version 1.2 ein Code-First-Framework, mit dem sich aus Sourcecode eine Swagger-Spezifikation im JSON-Format generieren ließ. Seit Version 2 wird auf einen Contract-First-Ansatz im YAML-Format gesetzt. Die Version 2 wurde von der Open API Initiative als Basis für die OpenAPI-Spezifikation übernommen. SwaggerHub bietet einen Online­editor an, mit dem sich ein API erstellen und validieren lässt (Abb. 1).

YAMLYAML ist eine Auszeichnungssprache zur Datenserialisierung und eine Übermenge von JSON. Das Akronym YAML steht für „YAML Ain’t Markup Language“. YAML ist leichter von Menschen zu lesen und zu schreiben als beispielsweise JSON oder XML.

Abb. 1: Mit dem SwaggerHub-Onlineeditor lassen sich APIs erstellen und validieren

In Listing 1 ist ein Ausschnitt der Swagger-Petstore-API-Demospezifikation zu sehen. Eine Swagger-Spezifikation muss immer Metainformationen wie einen Titel und eine Version enthalten. Der Hostname und ein Basispfad sind nicht zwingend notwendig. Anschließend können A...

Java Magazin
RESTful APIs dokumentieren

Eine gute Doku ist der Schlüssel

Der Begriff API-Economy taucht immer öfter auf und macht so deutlich, wie wichtig Web-APIs sind. Die Verbreitung und damit die Wettbewerbsfähigkeit eines Web-API steht und fällt mit einer guten Dokumentation. Denn sowohl öffentliche als auch interne APIs benötigen einen verständlichen Developer Guide, damit Entwickler sie einsetzen können. Mit den Open-Source-Projekten Swagger2Markup und AsciidoctorJ lässt sich ein Developer Guide erstellen, der sich mit handgeschriebener AsciiDoc-Dokumentation kombinieren lässt und sowohl offline als auch online lesbar ist.

Robert Winkler


In der letzten Zeit sind viele Spezifikationsformate und Frameworks entstanden, die Spezifikation und Dokumentation eines HTTP-basierten API vereinfachen und vereinheitlichen sollen. Zu den bekanntesten Spezifikationsformaten gehören Swagger (nun OpenAPI-Spezifikation [1]), RAML [2] oder API Blueprint [3]. All diese Projekte haben zum Ziel, ein Spezifikationsformat zu entwickeln, das zwar maschinenlesbar ist, aber mit dem in erster Linie Menschen arbeiten sollen. Sie nutzen hierfür unterschiedliche Formate wie JSON, YAML oder Markdown. Denn XML-basierte Formate wie die Web Application Description Language (WADL) eignen sich hierfür weniger. Diese Spezifikationsformate für sich alleine sind aber kein Developer Guide wie der GitHub API Developer Guide [4]. Developer Guides sollten weitere Informationen enthalten, wie ein Tutorial mit echten HTTP-Request- und -Response-Beispielen oder Codebeispiele und curl-Kommandos, mit denen sich das API testen lässt.

Swagger ist das momentan am weitesten verbreitete Spezifikationsformat für HTTP-basierte APIs. Um Swagger herum hat sich eine große Toollandschaft gebildet. Ein Beispiel ist die Onlinekollaborationsplattform SwaggerHub, die eine Zusammenarbeit an Swagger-Spezifikationen ermöglichen soll. SwaggerHub unterstützt den gesamten Lebenszyklus eines API und bietet hierfür einen Onlineeditor für das Erstellen einer Swagger-Spezifikation an sowie eine Integration mit GitHub, Versionisierung und Codegenerierung. Ursprünglich war Swagger in der Version 1.2 ein Code-First-Framework, mit dem sich aus Sourcecode eine Swagger-Spezifikation im JSON-Format generieren ließ. Seit Version 2 wird auf einen Contract-First-Ansatz im YAML-Format gesetzt. Die Version 2 wurde von der Open API Initiative als Basis für die OpenAPI-Spezifikation übernommen. SwaggerHub bietet einen Online­editor an, mit dem sich ein API erstellen und validieren lässt (Abb. 1).

YAMLYAML ist eine Auszeichnungssprache zur Datenserialisierung und eine Übermenge von JSON. Das Akronym YAML steht für „YAML Ain’t Markup Language“. YAML ist leichter von Menschen zu lesen und zu schreiben als beispielsweise JSON oder XML.

Abb. 1: Mit dem SwaggerHub-Onlineeditor lassen sich APIs erstellen und validieren

In Listing 1 ist ein Ausschnitt der Swagger-Petstore-API-Demospezifikation zu sehen. Eine Swagger-Spezifikation muss immer Metainformationen wie einen Titel und eine Version enthalten. Der Hostname und ein Basispfad sind nicht zwingend notwendig. Anschließend können A...

Neugierig geworden?


    
Loading...

Angebote für Teams

Für Firmen haben wir individuelle Teamlizenzen. Wir erstellen Ihnen gerne ein passendes Angebot.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang