OpenAPI Spezifikation

Der Industriestandard für REST API Dokumentation - und der Schlüssel zu schema-basierter API-Sicherheit.

Was ist OpenAPI?

Die OpenAPI Specification (früher Swagger) ist ein sprachunabhängiger Standard zur Beschreibung von REST APIs. Sie definiert Endpunkte, Parameter, Request/Response-Formate und Authentifizierung in einem maschinenlesbaren Format (YAML oder JSON).

OpenAPI 3.0 wird von der OpenAPI Initiative unter dem Dach der Linux Foundation entwickelt und ist der de-facto Standard für API-Dokumentation. Führende Unternehmen wie Google, Microsoft, IBM und Amazon nutzen OpenAPI für ihre APIs.

OpenAPI als Sicherheitsvertrag

  • Allowlist-Ansatz: Nur was explizit definiert ist, wird erlaubt
  • Vollständige Definition: Jeder Aspekt der API wird dokumentiert
  • Maschinenlesbar: Automatische Validierung jedes Requests
  • Bidirektional: Sowohl Requests als auch Responses werden validiert

Was OpenAPI validiert

Request-Validierung

  • Pfade: Nur definierte Endpunkte erlaubt
  • HTTP-Methoden: GET, POST, PUT, DELETE pro Pfad
  • Parameter: Typ, Format, Pattern-Validierung
  • Request Body: JSON Schema Validierung
  • Content-Type: Erlaubte Medientypen

Response-Validierung

  • Status Codes: Nur definierte Codes erlaubt
  • Response Body: JSON Schema Validierung
  • Felder: Nur definierte Properties
  • Formate: email, uri, date-time, etc.
  • Constraints: minLength, maxLength, etc.

OpenAPI Syntax-Beispiele

1. Pfad- und Methoden-Definition

Definieren Sie einen Endpunkt mit Pfadparametern und HTTP-Methode:

paths:
  /users/{userId}:
    get:
      summary: Benutzer nach ID abrufen
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
            minimum: 1

2. Request Body Schema

Definieren Sie die Struktur eines POST-Request-Bodys mit Validierungsregeln:

    post:
      summary: Neuen Benutzer anlegen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
              properties:
                email:
                  type: string
                  format: email
                  maxLength: 255
                name:
                  type: string
                  minLength: 2
                  maxLength: 100
                  pattern: '^[a-zA-Z ]+$'
              additionalProperties: false

Sicherheitshinweis: additionalProperties: false verhindert das Einschleusen unerwarteter Felder wie isAdmin: true

3. Response Schema

Definieren Sie, was die API zurückgeben darf - Signando REST validiert dies bidirektional:

      responses:
        '200':
          description: Benutzer gefunden
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  email:
                    type: string
                    format: email
                  name:
                    type: string
                  createdAt:
                    type: string
                    format: date-time
                additionalProperties: false
        '404':
          description: Benutzer nicht gefunden

Sicherheitshinweis: Response-Validierung verhindert Datenexfiltration - wenn ein kompromittiertes Backend versucht passwordHash zurückzugeben, blockiert Signando REST dies.

Ihre API mit OpenAPI absichern

Erfahren Sie, wie Signando REST Ihre OpenAPI-Spezifikation als Sicherheitsvertrag nutzt.

Beratung anfordern