OpenAPI und Swagger: API Dokumentation richtig machen

Gute API-Dokumentation ist der Schlüssel zu erfolgreichen Integrationen. OpenAPI (früher Swagger) ist der Industriestandard für die Beschreibung von REST APIs. In diesem Guide lernen Sie, wie Sie APIs professionell dokumentieren und dabei Zeit sparen.

Was ist OpenAPI (früher Swagger)?

Die OpenAPI Specification (OAS) ist ein sprachunabhängiges Format zur Beschreibung von REST APIs. Eine OpenAPI-Datei definiert Endpoints, Parameter, Request/Response-Formate, Authentifizierung und mehr in einem maschinenlesbaren Format (YAML oder JSON).

Der Name „Swagger“ bezeichnet heute das Tooling rund um OpenAPI: Swagger UI zur Visualisierung, Swagger Editor zum Erstellen und Swagger Codegen zur Code-Generierung. Die Spezifikation selbst heißt seit Version 3.0 offiziell OpenAPI.

OpenAPI Specification schreiben

Eine OpenAPI-Datei besteht aus mehreren Hauptabschnitten. Hier ist ein vollständiges Beispiel einer einfachen API:

# openapi.yaml
openapi: 3.1.0
info:
  title: Produkt-API
  description: API zur Verwaltung von Produkten
  version: 1.0.0
  contact:
    name: API Support
    email: api@example.com

servers:
  - url: https://api.example.com/v1
    description: Production Server
  - url: https://staging-api.example.com/v1
    description: Staging Server

tags:
  - name: Produkte
    description: Produktverwaltung
  - name: Kategorien
    description: Kategorieverwaltung

paths:
  /products:
    get:
      tags:
        - Produkte
      summary: Alle Produkte abrufen
      description: Gibt eine paginierte Liste aller Produkte zurück
      operationId: getProducts
      parameters:
        - name: page
          in: query
          description: Seitennummer
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Anzahl Produkte pro Seite
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: category
          in: query
          description: Nach Kategorie filtern
          schema:
            type: string
      responses:
        '200':
          description: Erfolgreiche Antwort
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'
        '400':
          description: Ungültige Parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    post:
      tags:
        - Produkte
      summary: Neues Produkt erstellen
      operationId: createProduct
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductInput'
      responses:
        '201':
          description: Produkt erstellt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          description: Nicht authentifiziert
        '422':
          description: Validierungsfehler
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'

  /products/{id}:
    get:
      tags:
        - Produkte
      summary: Einzelnes Produkt abrufen
      operationId: getProduct
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Erfolgreiche Antwort
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Produkt nicht gefunden

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    Product:
      type: object
      required:
        - id
        - name
        - price
      properties:
        id:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        name:
          type: string
          example: "Laptop Pro 15"
        description:
          type: string
          example: "High-End Laptop für Entwickler"
        price:
          type: number
          format: float
          example: 1299.99
        category:
          type: string
          example: "Electronics"
        createdAt:
          type: string
          format: date-time

    ProductInput:
      type: object
      required:
        - name
        - price
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
        price:
          type: number
          minimum: 0
        category:
          type: string

    ProductList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        pagination:
          $ref: '#/components/schemas/Pagination'

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string

    ValidationError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string

Swagger UI und Swagger Editor

Swagger UI

Swagger UI wandelt Ihre OpenAPI-Spezifikation in eine interaktive Dokumentation um. Entwickler können Endpoints direkt aus dem Browser testen, ohne Postman oder curl zu benötigen. Die Integration ist einfach:

// Express.js Integration
import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';

const swaggerDocument = YAML.load('./openapi.yaml');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
  customSiteTitle: 'Produkt-API Dokumentation',
  customCss: '.swagger-ui .topbar { display: none }'
}));

Swagger Editor

Der Swagger Editor unter editor.swagger.io ermöglicht das Erstellen und Validieren von OpenAPI-Spezifikationen mit Live-Vorschau. Syntax-Fehler werden sofort angezeigt, und die Dokumentation wird in Echtzeit aktualisiert. Für Teams gibt es auch VS Code Extensions mit ähnlicher Funktionalität.

API-First Design Ansatz

Beim API-First Design erstellen Sie die OpenAPI-Spezifikation vor der Implementierung. Dies hat mehrere Vorteile:

Code-Generierung aus OpenAPI

Eines der mächtigsten Features von OpenAPI ist die automatische Code-Generierung. Aus einer Spezifikation können Sie generieren:

# OpenAPI Generator installieren
npm install @openapitools/openapi-generator-cli -g

# TypeScript Client generieren
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./generated/client

# Server-Stub für Node.js generieren
openapi-generator-cli generate \
  -i openapi.yaml \
  -g nodejs-express-server \
  -o ./generated/server

# Python Client generieren
openapi-generator-cli generate \
  -i openapi.yaml \
  -g python \
  -o ./generated/python-client

Der generierte Code enthält typisierte Models, API-Clients mit allen Endpoints und oft auch Validierungslogik. Dies spart nicht nur Zeit, sondern garantiert auch Konsistenz zwischen Client und Server.

Alternative Dokumentations-Tools

Tool	Stärken	Ideal für
Swagger UI	Standard, Try-it-out	Interne APIs
Redoc	Schönes Design, Three-Panel	Öffentliche APIs
Stoplight	Visual Editor, Mock Server	API-First Teams
Readme.io	Guides + API Docs	Developer Portals
Postman	Testing + Docs	API-Entwicklung

Best Practices für API-Dokumentation