6.3    API-Dokumentation

Die letzte Ebene der Dokumentation, die wir Ihnen im Zuge dieses Kapitels vorstellen möchten, ist die API-Dokumentation und hier konkret die Dokumentation einer REST-API eines Webservices. Bei der Entwicklung von Webapplikationen haben Sie meist einen natürlichen Bruch zwischen Frontend und Backend. Die Endpunkte des Backends stellen lesende und schreibende Schnittstellen für das Frontend bereit. Häufig werden Frontend und Backend von unterschiedlichen Teams, teilweise sogar von unterschiedlichen Firmen, umgesetzt. Deshalb ist eine klare und saubere Kommunikation an dieser Stelle von großer Bedeutung.

Weit verbreitet für die Dokumentation von REST-APIs ist der OpenAPI-Standard, auch bekannt unter seinem früheren Namen »Swagger«. Je nach verwendeter Plattform beschreiben Sie die Schnittstellen Ihrer Applikation in einem separaten Dokument im YAML- oder JSON-Format oder direkt im Code als Kommentar oder mithilfe eines Decorators.

Beispiel für API-Dokumentation

Für die Erzeugung einer API-Dokumentation nutzen wir eine bestehende TypeScript-Applikation, die auf dem Express-Framework basiert. Für Express existiert eine Erweiterung mit dem Namen swagger-ui-express, die über einen gegebenen Pfad eine grafische Oberfläche mit der API-Dokumentation zur Verfügung stellt. Die Erweiterung liest ihre Konfiguration in unserem Beispiel aus einer Swagger-Datei, die anfangs noch leer ist, und stellt die Dokumentation über den Pfad /api zur Verfügung.

Die Applikation hat einen Endpunkt mit dem Pfad /users, über den User-Daten im JSON-Format ausgeliefert werden. Die Daten stammen aus einer Klasse UserService und sind Instanzen der Klasse User. Der Code der Einstiegsdatei der Applikation sieht folgendermaßen aus:

import { readFileSync } from "node:fs";
import express from "express";
import swaggerUi from "swagger-ui-express";
import * as YAML from "yaml";
import UserService from "./user.service.js";

const app = express();

const yamlSpec = readFileSync("./swagger.yaml", "utf8");
const swaggerDocument = YAML.parse(yamlSpec);

app.use(
  "/api",
  swaggerUi.serve,
  swaggerUi.setup(swaggerDocument)
);

const userService = new UserService();
app.get("/users", (request, response) => {
  response.json(userService.getAll());
});

app.listen(3000, () => {
  console.log("Server is running on port 3000");
});

Zur Generierung der API-Dokumentation nutzen wir in diesem Fall die GitHub-Copilot-Extension für VS Code. Öffnen Sie in Ihrer Entwicklungsumgebung die Datei swagger.yaml, können Sie über das Chat-Feature den folgenden Prompt absetzen:

Prompt: Please create an api documentation for the express application in #file:index.ts using the user class in #file:user.ts. Please include example data.

Certainly! Here’s an example of how you can create an API documentation using Swagger YAML in the swagger.yaml file:

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
servers:
  - url: http://localhost:3000
paths:
  /api/users:
    get:
      summary: Get all users
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        name:
          type: string
          example: John Doe
        email:
          type: string
          example: johndoe@example.com
        password:
          type: string
          example: password123

Der Kontext einer API-Dokumentation ist deutlich umfangreicher als der einer einfachen Funktion oder Klasse. Die API ist der Einstiegspunkt für die Client-Server-Kommunikation. Der zugehörige Quellcode umfasst nicht nur eine einzelne Datei, sondern in der Regel mehrere. Im Beispiel sind das die Einstiegsdatei index.ts und die user.ts-Datei mit der Definition der Struktur. Diese müssen Sie der KI zur Verfügung stellen, um ein sinnvolles Ergebnis zu erhalten.

Der Copilot liefert bis auf einen kleinen Fehler genau das Ergebnis, das wir erwarten. Lediglich den Pfad /api/users müssen Sie in /users ändern. Ansonsten passen sowohl die allgemeinen Informationen als auch die Dokumentation für den Endpunkt und die Datenstruktur mit den geforderten Beispieldaten. Übernehmen Sie den Code und laden Sie Ihre Applikation neu, können Sie über http://localhost:3000/api auf die Swagger-UI zugreifen und von dort aus Ihren Endpunkt testen.

Abbildung 6.1     Ansicht der Swagger-UI

Über en Button Try it out und in der Folge Execute können Sie die Anfrage an den Server senden und Ihren Endpunkt testen. Durch die Konfiguration gibt Ihnen die grafische Schnittstelle nicht nur Informationen über Pfad und HTTP-Methode, sondern auch zur Struktur der Antwort sowie zu den zugehörigen Beispieldaten.