OpenAPI / Swagger

Einfach erklärt

OpenAPI ist ein Standard, um REST-APIs zu beschreiben. Statt Dokumentation manuell zu schreiben, definierst du die API in einem strukturierten Format – und Tools generieren Docs, Tests und Code automatisch.

Vorher (ohne OpenAPI):

Dokumentation: Word-Dokument, veraltet nach 2 Wochen
Testing: Postman-Collection, manuell gepflegt
Client-Code: Jeder schreibt eigenen HTTP-Code

Nachher (mit OpenAPI):

openapi.yaml → Swagger UI (Docs)
             → Postman Import (Testing)
             → SDK Generator (Client-Code)
             → Server Stubs (Backend)

Beispiel OpenAPI-Spec:

openapi: 3.1.0
info:
  title: User API
  version: 1.0.0

paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email

Technischer Deep Dive

OpenAPI-Struktur

openapi: 3.1.0           # Version

info:                     # Metadaten
  title: My API
  version: 1.0.0
  description: API description

servers:                  # Basis-URLs
  - url: https://api.example.com/v1

paths:                    # Endpunkte
  /resource:
    get: ...
    post: ...

components:               # Wiederverwendbare Teile
  schemas: ...            # Datenmodelle
  parameters: ...         # Parameter
  responses: ...          # Response-Definitionen
  securitySchemes: ...    # Auth-Methoden

security:                 # Globale Security
  - bearerAuth: []

Authentifizierung definieren

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
    
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            read: Read access
            write: Write access

security:
  - bearerAuth: []

Request/Response Bodies

paths:
  /users:
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                email:
                  type: string
                  format: email
            example:
              name: "Max Mustermann"
              email: "max@example.com"
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Code-Generierung

Client generieren:

openapi-generator generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./generated-client

Unterstützte Sprachen (Auswahl):

• TypeScript (Axios, Fetch, Angular)
• Python (requests, aiohttp)
• Java (OkHttp, Retrofit)
• Go, Rust, C#, Ruby, PHP…

Spec-First vs. Code-First

Ansatz	Beschreibung	Vorteile
Spec-First	Erst Spec schreiben, dann implementieren	Sauberer Contract, bessere Planung
Code-First	Spec aus Code generieren	Schneller, immer synchron

Code-First Beispiel (FastAPI):

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    id: int
    name: str
    email: str

@app.get("/users/{user_id}", response_model=User)
async def get_user(user_id: int):
    ...

# OpenAPI-Spec automatisch unter /openapi.json

Validierung

# Spec validieren
npx @redocly/cli lint openapi.yaml

# Request/Response gegen Spec validieren
# (in Tests oder als Middleware)