Menü

Asynchrone API's dokumentieren

  • von Azmir Abdi
von Jens Nickles, Daniel Bantel, Daniel Mwasi und Azmir Abdi

Wie dokumentiert man synchrone Schnittstellen um diese testen und veröffentlichen zu können? 
OpenAPI (https://www.openapis.org/) ist mittlerweile ein sehr gut beschriebener Standard für synchrone Schnittstellen. Mit Swagger (https://swagger.io/) stehen ausreichend Tools für die Implementierung zur Verfügung.

Aber was ist mit der Dokumentation asynchroner Schnittstellen? Ob man eine asynchrone Schnittstelle als externe API veröffentlichen sollte oder nicht wird hier nicht betrachtet. Es wird davon ausgegangen, dass es Anwendungsfälle gibt, für die dies notwendig ist.
Für diese Anwendungsfälle stellt sich dann die Frage, wie diese spezifiziert werden könnten.

Wozu eine API-Spezifikation?

Eine API Spezifikation unterstützt die folgenden Use-Cases im Software-Engineering:

  • Eine API Spezifikationen sollte eine Schnittstelle voll umfänglich dokumentieren.

  • Aus der Dokumentation sollten Use-Cases wie Code-Generierung(maven, gradle), Veröffentlichung, Durchsuchen, (An-)Testen und Einbindung/Integration weitestgehend unterstützt werden.

  • Es sollte eine maschinell-automatisierte Verarbeitung aller Use-Cases angestrebt werden.

Was gehört in eine API-Spezifikation?

Folgende Informationen sollte eine voll umfängliche API-Spezifikation liefern:

  • Meta-Informationen wie Name und Version der API
  • Technische Beschreibung für die Einbindung wie Protokoll, Host Url, Port usw.
  • Security (End-To-End, Point-To-Point)
  • Format und Kodierung des Inhalts/Payloads (Json, XML, ...)
  • Beschreibung der Struktur der Nachrichten (Domäne, Objekte, Optionale- & Pflichtfelder, Beschreibung der möglichen Werte, Validierungsregeln)
  • Beispiele der Nachrichten mit vorgefüllten Werten (Request, Event)
  • Beschreibung der möglichen Antworten/Fehlerausprägungen

Erstellung einer asnychronen API Spezifikation mit AsyncAPI

Der OpenAPI Standard für die Beschreibung von Schnittstellen bringt mit der Swagger Implementierung so gut wie alle benötigten Funktionalitäten mit. Jedoch ist der Standard nur für synchrone Schnittstellen über das HTTP Protokoll (Request-Response) ausgelegt und unterstützt asynchrone Schnittstellen nicht. Aufgrund dieser Lücke wurde die Open Source Initiative AsyncAPI gegründet (siehe https://www.asyncapi.com/).

Die Initiative ist aktuell dabei die Version 2.0.0 des AsyncAPI Standards zu veröffentlichen. Der Standard setzt auf OpenAPI auf und sieht entsprechend ähnlich aus.

Wie man dem folgenden Beispiel entnehmen kann, ist die AsynAPI Spezifikation der OpenAPI Spezifikation sehr ähnlich und basiert auf dem JSON/YML Format. Die eingebetteten Schema Objekte werden nach JsonSchema aufgebaut (https://json-schema.org).

AsynAPI Beispiel
asyncapi: "1.2.0"
info:
  title: sidion codeReview AsyncAPI AMQP consumer
  description: |
    This is a simple example of a AsyncAPI document for integration of AMQP topic.
  termsOfService: https://www.sidion.de/datenschutz.html
  contact:
    name: sidion
    url: https://www.sidion.de/
    email: info@sidion.de
  version: "0.0.1-SNAPSHOT"
  
servers:
  - url: "{host}:{port}"
    description: Connection to RabbitMQ using the AMQP protocol.
    scheme: amqp
    variables:
      host:
        default: "localhost"
      port:
        default: '5672'
  
topics:
  codeReviewQueue:
    x-service-name: codeReviewService
    subscribe:
      $ref: "#/components/messages/codeReviewMessage"
  
components:
  messages:
    codeReviewMessage:
      summary: Information about code review.
      payload:
        $ref: "#/components/schemas/codeReviewPayload"
  schemas:
    codeReviewPayload:
      type: object
      properties:
        id:
          type: integer
          minimum: 0
          description: Identifier Number.
        reviewNote:
          type: string
          description: Review note to the developed code.
        user:
          $ref: "#/components/schemas/userCreate"
        sentAt:
          $ref: "#/components/schemas/sentAt"
    userCreate:
      type: string
      format: string
      description: User id of the review user.
    sentAt:
      type: string
      format: date-time
      description: Date and time information regarding when the message was sent.

AsyncAPI Version 1.2.0:

https://www.asyncapi.com/docs/specifications/1.2.0/

Vergleich AsyncAPI v1.2.0 vs. OpenAPI v3.0.2

Generierung der Dokumentation

NodeJs > Version 6 asyncapi-generator installieren:

> npm install -g asyncapi-generator

Und aus der AsyncAPI Datei HTML Dokumentation generieren:

npm command
> ag -o \sidionAsyncApi sidionAsyncAPI.yml html

Es wird folgendes Ergebnis generiert:

  |_sidionAsyncApi 
      |_css
          |_main.css
      |_ index.html

mit folgender HTML Darstellung:

HTML Output

Wie der github Seite des asyncapi-generator Projektes entnommen werden kann, werden neben HTML weitere Ziel-Templates unterstützt wie Node.js/Hermes, Java/Spring und Markdown.

Fazit

Wenn man HTML oder Markdown Dokumentation von asynchronous Interfaces veröffentlichen möchte, bietet AsyncAPI aktuell eine gute Möglichkeit, mit dem asyncapi-Generator eine passende Dokumentation zu generieren.
Durch den Einsatz von JSON Schema für die Beschreibung der Objekte lassen sich diese auch ausgelagert in dem AsyncAPI File wiederverwenden.

Eine weiterführende Unterstützung der bisher noch nicht vorhandenen Tools wird in der kurz vor ihrer Veröffentlichung stehenden Version 2.0.0 erwartet.

Wir sind sehr darauf gespannt und werden diese nach Veröffentlichung evaluieren.

 

Zurück