So dokumentierst du eine API mit Swagger – Schritt für Schritt

10. Februar 2025 | 6 Min.

Author: dataliquid GmbH

Installation und Einrichtung von Swagger

Swagger ist ein leistungsstarkes Open-Source-Tool zur API-Dokumentation. Es dient der strukturierten Beschreibung, Visualisierung und Interaktion mit APIs. Entwickler profitieren von einer klaren, interaktiven Dokumentation, die die Nutzung und Wartung von APIs erheblich erleichtert. Mit Swagger können API-Spezifikationen übersichtlich erfasst und dargestellt werden, wodurch der aktuelle Stand einer API präzise abgebildet wird. Dies fördert nicht nur die Nachvollziehbarkeit, sondern erleichtert auch die Zusammenarbeit zwischen Entwicklern. Vor der Nutzung von Swagger muss es je nach Technologie-Stack installiert und eingerichtet werden, wobei verschiedene Integrationsmöglichkeiten zur Verfügung stehen.

Installation

Je nach Technologie-Stack gibt es verschiedene Möglichkeiten, Swagger zu integrieren. Die gängigsten Optionen sind:

  • Swagger UI, eine Benutzeroberfläche zur Visualisierung und Interaktion mit API-Dokumentationen. Diese kann über ein CDN oder lokal eingebunden werden und bietet eine interaktive Ansicht der API.

  • Swagger Editor, ein Online-Editor, mit dem API-Spezifikationen direkt geschrieben und getestet werden können. Dies erleichtert die Erstellung und Anpassung der Dokumentation erheblich.

  • Swagger Codegen, ein Tool zur Generierung von API-Client-Bibliotheken und Server-Stubs aus einer Swagger-Spezifikation. Damit lassen sich verschiedene Programmiersprachen unterstützen und eine automatische Codegenerierung ermöglichen.

  • Swagger für verschiedene Frameworks, wie z. B.:

    • Node.js (Express.js): Installation mit npm install swagger-ui-express

    • Spring Boot (Java): Integration mit springfox-swagger2

    • Python (Flask): Nutzung von flasgger

Einrichtung

Nach der Installation muss Swagger in das Projekt eingebunden werden. Die Einbindung hängt von der verwendeten Umgebung ab. In einer Express.js-Anwendung sieht die Integration beispielsweise folgendermaßen aus:

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
const app = require('express')();

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.listen(3000, () => console.log('Server läuft auf Port 3000'));

Sobald die Anwendung gestartet wurde, kann die API-Dokumentation im Browser unter http://localhost:3000/api-docs aufgerufen werden. Dort sind alle Endpunkte übersichtlich dargestellt und können interaktiv getestet werden.

Swagger API Endpunkte erstellen: Erste Schritte

Um eine API mit Swagger zu dokumentieren, muss eine Swagger 2.0-Spezifikation erstellt werden. Diese kann in YAML oder JSON geschrieben werden und beschreibt die API-Endpunkte detailliert. Dabei werden nicht nur die verfügbaren Routen definiert, sondern auch die erwarteten Parameter und Antwortstrukturen festgelegt.

Ein einfaches Beispiel für einen API-Endpunkt könnte folgendermaßen aussehen:

swagger: '2.0'
info:
  title: Beispiel API
  description: Eine einfache API zur Demonstration von Swagger
  version: 1.0.0
host: localhost:3000
schemes:
  - http
paths:
  /users:
    get:
      summary: Liste aller Benutzer abrufen
      produces:
        - application/json
      responses:
        '200':
          description: Erfolgreiche Antwort
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  type: integer
                name:
                  type: string

Components: Wiederverwendbare Definitionen

Swagger ermöglicht die Wiederverwendung von Komponenten wie Schemas, Parametern und Antworten, um eine konsistente und wartbare API-Dokumentation zu gewährleisten. Die components-Sektion in OpenAPI 3.0 entspricht in Swagger 2.0 der definitions-Sektion.

Ein Beispiel für eine Wiederverwendung von Definitionen:

swagger: '2.0'
info:
  title: API mit wiederverwendbaren Komponenten
  version: 1.0.0
host: localhost:3000
schemes:
  - http
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
paths:
  /users:
    get:
      summary: Liste aller Benutzer abrufen
      produces:
        - application/json
      responses:
        '200':
          description: Erfolgreiche Antwort
          schema:
            type: array
            items:
              $ref: '#/definitions/User'

Hier wird das User-Schema in der definitions-Sektion definiert und anschließend bei der Antwort des /users-Endpoints wiederverwendet. Änderungen an diesem Schema wirken sich auf alle Endpunkte aus, die diese Definition referenzieren, wodurch Konsistenz gewahrt bleibt. Allerdings sollten Änderungen mit Bedacht durchgeführt werden, um unerwartete Auswirkungen auf bestehende API-Clients zu vermeiden. Dies sorgt für eine bessere Wartbarkeit, da Änderungen nur an einer Stelle vorgenommen werden müssen.

Security: API-Authentifizierung und Autorisierung

Eine gut gesicherte API ist essenziell, um unberechtigten Zugriff zu verhindern. Dabei ist es wichtig, zwischen Authentifizierung und Autorisierung zu unterscheiden. Die Authentifizierung stellt sicher, dass ein Nutzer oder System tatsächlich derjenige ist, der er vorgibt zu sein (z. B. durch API-Keys oder OAuth2). Die Autorisierung hingegen bestimmt, welche Aktionen ein authentifizierter Nutzer durchführen darf (z. B. Lese- oder Schreibrechte). Swagger 2.0 unterstützt verschiedene Authentifizierungsmethoden, darunter API-Keys, OAuth2 und Basic Authentication.

Ein Beispiel für eine API, die mit einem API-Key geschützt ist:

swagger: '2.0'
info:
  title: Geschützte API
  version: 1.0.0
host: localhost:3000
schemes:
  - http
securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key
paths:
  /secure-data:
    get:
      summary: Geschützte Daten abrufen
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Erfolgreiche Antwort
          schema:
            type: object
            properties:
              data:
                type: string

OAuth 2.0 Authentifizierung

Eine moderne und flexible Methode zur Authentifizierung ist OAuth 2.0. Damit können sich Nutzer sicher bei der API authentifizieren.

securityDefinitions:
  OAuth2:
    type: oauth2
    flow: accessCode
    authorizationUrl: https://example.com/oauth/authorize
    tokenUrl: https://example.com/oauth/token
    scopes:
      read: Zugriff auf geschützte Ressourcen
paths:
  /user-info:
    get:
      summary: Benutzerinformationen abrufen
      security:
        - OAuth2:
            - read
      responses:
        '200':
          description: Erfolgreiche Antwort
          schema:
            type: object
            properties:
              username:
                type: string

Hier wird sichergestellt, dass der Endpunkt /user-info nur für authentifizierte Nutzer mit dem entsprechenden OAuth2-Token zugänglich ist. Der Scope read erlaubt es Nutzern, auf geschützte Ressourcen lesend zuzugreifen, ohne Änderungen vorzunehmen. Dies eignet sich für Endpunkte, die sensible, aber unveränderbare Informationen bereitstellen, wie z. B. Profildaten oder Systemstatus.

Ein Beispiel für eine API, die mit einem API-Key geschützt ist:

swagger: '2.0'
info:
  title: Geschützte API
  version: 1.0.0
host: localhost:3000
schemes:
  - http
securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key
paths:
  /secure-data:
    get:
      summary: Geschützte Daten abrufen
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Erfolgreiche Antwort
          schema:
            type: object
            properties:
              data:
                type: string

Best Practices für eine gut strukturierte API-Dokumentation

Um eine API-Dokumentation optimal zu gestalten, sollten einige Best Practices beachtet werden:

  1. Konsistente Struktur: Eine gut organisierte API-Dokumentation erleichtert das Verständnis und sorgt für eine einheitliche Dokumentation aller Endpunkte. Dies kann in Form von API Design Guidelines zusammengefasst werden, die unter anderem Konventionen für Namensgebung, Versionierung und Sicherheitsaspekte festlegen.

  2. Aussagekräftige Beschreibungen: Jeder Endpunkt sollte detaillierte Beschreibungen enthalten, damit Nutzer sofort erkennen, wie er funktioniert. Beispielsweise könnte der Endpunkt /users mit der Beschreibung Gibt eine Liste aller registrierten Benutzer zurück. Optional kann über einen Query-Parameter nach bestimmten Namen gefiltert werden. versehen werden. Dies hilft Entwicklern, den Zweck und die möglichen Einsatzmöglichkeiten des Endpunkts besser zu verstehen.

  3. Beispieldaten bereitstellen: Durch die Verwendung von example oder examples kann ein realistischer Eindruck der API-Antworten vermittelt werden. Beispielsweise könnte ein Endpunkt, der Benutzerinformationen zurückliefert, eine Beispielantwort mit id: 1 und name: 'Max Mustermann' enthalten, um den erwarteten Datenaufbau zu verdeutlichen.

  4. Authentifizierung angeben: Falls eine Authentifizierung erforderlich ist, sollte diese klar dokumentiert werden, z. B. durch die Verwendung von API-Keys oder OAuth. API-Keys sind einfach zu implementieren und eignen sich gut für serverseitige Anwendungen, können jedoch unsicher sein, wenn sie in Clients offengelegt werden. OAuth bietet ein sichereres Authentifizierungsverfahren mit Token-basiertem Zugriff, ist jedoch komplexer in der Implementierung und erfordert zusätzliche Infrastruktur wie einen Autorisierungsserver.

  5. Versionskontrolle: Eine API entwickelt sich weiter. Durch klare Versionskennzeichnungen kann sichergestellt werden, dass Nutzer immer die richtige Dokumentation verwenden. Zum Beispiel kann eine API-Version in der URL definiert werden (/v1/users) oder durch das info.version-Attribut in Swagger (version: '1.0.0'). Dies hilft, ältere Versionen zu unterstützen und neue Features schrittweise einzuführen. Die Verwendung des Semantic Versioning (SemVer) Ansatzes (MAJOR.MINOR.PATCH) ermöglicht es Entwicklern, Änderungen transparent zu kommunizieren, indem beispielsweise eine Erhöhung der Major-Version (v2.0.0) auf inkompatible Änderungen hinweist, während Minor-Updates (v1.1.0) neue Funktionen ohne Breaking Changes hinzufügen.

  6. Wiederverwendbare Komponenten nutzen: Häufig verwendete Elemente wie Schemas, Parameter oder Antworten sollten in definitions (Swagger 2.0) gespeichert werden. Dadurch wird die API-Dokumentation konsistenter und leichter wartbar. Swagger erlaubt verschiedene Definitionstypen, darunter definitions für Datenmodelle, parameters für wiederverwendbare Parameter, responses für vordefinierte API-Antworten und securityDefinitions zur Authentifizierung. Beispielsweise kann eine Benutzerstruktur einmalig definiert und mehrfach referenziert werden: $ref: '#/definitions/User'.

  7. Interaktive Swagger UI nutzen: Eine interaktive Dokumentation erleichtert Entwicklern das Testen der API und reduziert den Kommunikationsaufwand.

Fazit

Mit diesen Schritten und bewährten Methoden gelingt eine professionelle API-Dokumentation mit Swagger 2.0. Eine gepflegte und gut strukturierte API-Dokumentation erleichtert nicht nur Entwicklern die Implementierung, sondern verbessert auch die Zusammenarbeit mit anderen Teams, fördert die Wartbarkeit und erhöht die Transparenz der API-Nutzung. Eine gut strukturierte Dokumentation ist ein essenzieller Bestandteil jeder API-Entwicklung, da sie nicht nur Entwicklern hilft, sondern auch die Zusammenarbeit in Teams verbessert.