Zum Hauptinhalt springen

Einführung in den OpenAPI-Standard

Der OpenAPI-Standard ist eine weit verbreitete Spezifikation zur Beschreibung von RESTful APIs. Er ermöglicht Entwicklern, die Struktur und Funktionalität eines Webservices in einer maschinenlesbaren und standardisierten Form zu dokumentieren. Dadurch wird die Integration, Wartung und Weiterentwicklung von APIs erheblich vereinfacht.

Was ist OpenAPI?​

OpenAPI, früher bekannt als Swagger Specification, ist eine Spezifikation zur Beschreibung von HTTP-basierten APIs. Mit OpenAPI können Entwickler:

  • API-Endpunkte definieren
  • HTTP-Methoden (GET, POST, PUT, DELETE usw.) beschreiben
  • Anfrage- und Antwortformate spezifizieren
  • Sicherheitsmechanismen dokumentieren

Die Spezifikation kann in YAML oder JSON geschrieben werden und dient als Grundlage für die automatische Generierung von Dokumentationen, Client-Bibliotheken und Server-Stubs.

Grundstruktur einer OpenAPI Spezifikation​

Eine typische OpenAPI-Datei besteht aus mehreren Hauptkomponenten:

  • openapi: Die verwendete Version der OpenAPI-Spezifikation.
  • info: Metadaten zur API wie Titel, Beschreibung und Version.
  • servers: Die Basis-URLs, unter denen die API erreichbar ist.
  • paths: Die verfügbaren API-Endpunkte und ihre Operationen.
  • components: Wiederverwendbare Schema-Definitionen, Sicherheitsschemata usw.

Einfaches Beispiel​

openapi: 3.1.0
info:
  title: Meine Beispiel-API
  version: 1.0.0
servers:
  - url: https://api.beispiel.de/v1
paths:
  /benutzer:
    get:
      summary: Liste aller Benutzer abrufen
      responses:
        '200':
          description: Erfolgreiche Antwort
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Benutzer'
components:
  schemas:
    Benutzer:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Hauptkomponenten im Detail​

Info​

Der info-Abschnitt enthält grundlegende Informationen über die API.

info:
  title: Meine Beispiel-API
  description: Eine API zur Demonstration des OpenAPI-Standards.
  version: 1.0.0

Servers​

Definiert die Basis-URLs der API.

servers:
  - url: https://api.beispiel.de/v1
    description: Hauptserver

Paths​

Hier werden die verfügbaren Endpunkte und ihre jeweiligen HTTP-Methoden beschrieben.

paths:
  /benutzer/{id}:
    get:
      summary: Einzelnen Benutzer abrufen
      parameters:
        - name: id
          in: path
          required: true
          description: Die ID des Benutzers
          schema:
            type: integer
      responses:
        '200':
          description: Erfolgreiche Antwort
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Benutzer'

Components​

Enthält wiederverwendbare Definitionen wie Schemas, Parameter und Sicherheitsmechanismen.

components:
  schemas:
    Benutzer:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

Vorteile des OpenAPI-Standards​

  • Automatisierte Dokumentation: Tools können aus der Spezifikation automatisch lesbare Dokumentationen erstellen.
  • Code-Generierung: Client-Bibliotheken und Server-Stubs können automatisch generiert werden.
  • Konsistenz: Einheitliche Beschreibung von APIs erleichtert die Zusammenarbeit zwischen Teams.
  • Validierung: Anfragen und Antworten können gegen die Spezifikation validiert werden.

Tools und Ökosystem​

Es gibt zahlreiche Tools, die den OpenAPI-Standard unterstützen:

  • Swagger UI: Generiert eine interaktive HTML-Dokumentation aus der OpenAPI-Spezifikation.
  • Swagger Editor: Ein webbasierter Editor zum Erstellen und Bearbeiten von OpenAPI-Dateien.
  • OpenAPI Generator: Generiert Client-Bibliotheken und Server-Stubs in verschiedenen Programmiersprachen.
  • Postman: Importiert OpenAPI-Spezifikationen für API-Tests und Dokumentation.

Best Practices​

Konsistente Benennung​

Verwende klare und einheitliche Namen für Endpunkte, Parameter und Schemas.

Verwendung von Schemas​

Definiere Datenmodelle unter components/schemas und referenziere sie in den Pfaden.

components:
  schemas:
    Fehler:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string

Dokumentation von Fehlern​

Beschreibe auch mögliche Fehlerantworten, nicht nur erfolgreiche Antworten.

responses:
  '400':
    description: Ungültige Anfrage
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Fehler'

Sicherheitsmechanismen​

Definiere Authentifizierungs- und Autorisierungsmechanismen unter components/securitySchemes.

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

Und verwende sie in den Pfaden oder global:

security:
  - ApiKeyAuth: []

Beispiel einer vollständigen OpenAPI-Spezifikation (Version 3.1.0)​

Ein erweitertes Beispiel könnte so aussehen:

openapi: 3.1.0
info:
  title: Aufgaben-API
  version: 1.0.0
servers:
  - url: https://api.aufgaben.de/v1
paths:
  /aufgaben:
    get:
      summary: Liste aller Aufgaben abrufen
      responses:
        '200':
          description: Erfolgreiche Antwort
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Aufgabe'
    post:
      summary: Neue Aufgabe erstellen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Aufgabe'
      responses:
        '201':
          description: Aufgabe erstellt
components:
  schemas:
    Aufgabe:
      type: object
      required:
        - titel
      properties:
        id:
          type: integer
        titel:
          type: string
        erledigt:
          type: boolean
          default: false