OpenAPI ist eine Spezifikation zur Beschreibung von APIs. Mintlify unterstützt OpenAPI-3.0+-Dokumente, um interaktive API-Dokumentation zu generieren und sie stets auf dem neuesten Stand zu halten.

​
Eine OpenAPI-Spezifikationsdatei hinzufügen

Um Ihre Endpunkte mit OpenAPI zu dokumentieren, benötigen Sie ein gültiges OpenAPI-Dokument im JSON- oder YAML-Format, das der OpenAPI-Spezifikation 3.0+ entspricht. Sie können API-Seiten aus einem oder mehreren OpenAPI-Dokumenten erstellen.

​
Ihre API beschreiben

Wir empfehlen die folgenden Ressourcen, um sich mit OpenAPI vertraut zu machen und Ihre OpenAPI-Dokumente zu erstellen.
Der Swagger OpenAPI-Leitfaden bezieht sich auf OpenAPI v3.0, aber nahezu alle Informationen sind auch für v3.1 relevant. Weitere Informationen zu den Unterschieden zwischen v3.0 und v3.1 finden Sie im OpenAPI‑Blog unter Migration von OpenAPI 3.0 auf 3.1.0.

​
Die URL für Ihre API festlegen

Um Mintlify-Funktionen wie die API-Spielwiese zu aktivieren, fügen Sie Ihrem OpenAPI-Dokument ein servers-Feld mit der Basis-URL Ihrer API hinzu. 
{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}
In einem OpenAPI-Dokument werden verschiedene API-Endpunkte über ihre Pfade definiert, etwa /users/{id} oder einfach /. Die Basis-URL legt fest, wo diese Pfade angehängt werden. Weitere Informationen zur Konfiguration des servers-Felds finden Sie in der OpenAPI-Dokumentation unter API Server and Base Path. Die API-Spielwiese verwendet diese Server-URLs, um zu bestimmen, wohin Anfragen gesendet werden. Wenn Sie mehrere Server angeben, können Nutzer in einem Dropdown zwischen ihnen wechseln. Wenn Sie keinen Server angeben, nutzt die API-Spielwiese den einfachen Modus, da ohne Basis-URL keine Anfragen gesendet werden können. Wenn Ihre API Endpunkte hat, die unter unterschiedlichen URLs verfügbar sind, können Sie das Server-Feld überschreiben – für einen bestimmten Pfad oder eine bestimmte Operation.

​
Authentifizierung festlegen

Um die Authentifizierung in Ihrer API-Dokumentation und der API-Spielwiese zu aktivieren, konfigurieren Sie die Felder securitySchemes und security in Ihrem OpenAPI-Dokument. Die API-Beschreibungen und die API-Spielwiese fügen auf Basis der Sicherheitskonfigurationen in Ihrem OpenAPI-Dokument die entsprechenden Authentifizierungsfelder hinzu.
1

Authentifizierungsmethode definieren.

Fügen Sie ein Feld securitySchemes hinzu, um festzulegen, wie sich Nutzer authentifizieren.Dieses Beispiel zeigt eine Konfiguration für Bearer-Authentifizierung.
{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
2

Authentifizierung auf Endpunkte anwenden.

Fügen Sie ein Feld security hinzu, um Authentifizierung zu erzwingen.
{
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
Häufige Authentifizierungsarten sind:
  • API Keys: Für Header-, Query- oder Cookie-basierte Schlüssel.
  • Bearer: Für JWT- oder OAuth-Token.
  • Basic: Für Benutzername und Passwort.
Wenn unterschiedliche Endpunkte innerhalb Ihrer API unterschiedliche Authentifizierungsmethoden erfordern, können Sie für eine bestimmte Operation das Feld security überschreiben. Weitere Informationen zum Definieren und Anwenden von Authentifizierung finden Sie in der OpenAPI-Dokumentation unter Authentication.

​
x-mint-Erweiterung

Die x-mint-Erweiterung ist eine benutzerdefinierte OpenAPI-Erweiterung, die Ihnen zusätzliche Kontrolle darüber gibt, wie Ihre API-Dokumentation erzeugt und dargestellt wird.

​
Metadaten

Überschreiben Sie die Standardmetadaten für generierte API-Seiten, indem Sie x-mint: metadata zu einer beliebigen Operation hinzufügen. Sie können jedes Metadatenfeld verwenden, das in MDX-Frontmatter gültig wäre, mit Ausnahme von openapi: 
{
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "description": "Retrieve a list of users",
        "x-mint": {
          "metadata": {
            "title": "List all users",
            "description": "Fetch paginated user data with filtering options",
            "og:title": "Display a list of users"
          }
        },
        "parameters": [
          {
            // Parameterkonfiguration
          }
        ]
      }
    }
  }
}

​
Inhalt

Fügen Sie vor der automatisch generierten API-Dokumentation mit x-mint: content eigenen Inhalt hinzu: 
{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create user",
        "x-mint": {
          "content": "## Voraussetzungen\n\nDieser Endpunkt erfordert Adminrechte und unterliegt einer Ratenbegrenzung.\n\n<Note>Benutzer-E-Mail-Adressen müssen im gesamten System eindeutig sein.</Note>"
        },
        "parameters": [
          {
            // Parameterkonfiguration
          }
        ]
      }
    }
  }
}
Die Erweiterung content unterstützt alle Mintlify MDX-Komponenten und Formatierungen.

​
Href

Ändern Sie die URL der Endpunktseite in Ihrer Dokumentation mit x-mint: href: 
{
  "paths": {
    "/legacy-endpoint": {
      "get": {
        "summary": "Legacy endpoint",
        "x-mint": {
          "href": "/deprecated-endpoints/legacy-endpoint"
        }
      }
    },
    "/documented-elsewhere": {
      "post": {
        "summary": "Special endpoint",
        "x-mint": {
          "href": "/guides/special-endpoint-guide"
        }
      }
    }
  }
}
Wenn x-mint: href vorhanden ist, verweist der Navigationseintrag direkt auf die angegebene URL, statt eine API-Seite zu generieren.

​
MCP

Stellen Sie Endpunkte selektiv als Model Context Protocol (MCP)-Tools bereit, indem Sie x-mint: mcp verwenden. Aktivieren Sie nur Endpunkte, die für den öffentlichen Zugriff über KI-Tools sicher sind.
​
mcp
object
Die MCP-Konfiguration für den Endpunkt.
{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create user",
        "x-mint": {
          "mcp": {
            "enabled": true
          },
          // ...
        }
      }
    },
    "/users": {
      "delete": {
        "summary": "Delete user (admin only)",
        // No `x-mint: mcp` so this endpoint is not exposed as an MCP tool
        // ...
      }
    }
  }
}
Weitere Informationen finden Sie unter Model Context Protocol.

​
API-Seiten automatisch befüllen

Fügen Sie einem beliebigen Navigationselement in Ihrer docs.json ein openapi-Feld hinzu, um Seiten für OpenAPI-Endpunkte automatisch zu generieren. Sie können steuern, wo diese Seiten in Ihrer Navigationsstruktur erscheinen – als eigene API-Bereiche oder gemeinsam mit anderen Seiten. Das openapi-Feld akzeptiert entweder einen Dateipfad in Ihrem Docs-Repository oder eine URL zu einem gehosteten OpenAPI-Dokument. Generierte Endpunktseiten haben diese Standardmetadaten:
  • title: Das summary-Feld der Operation, falls vorhanden. Ohne summary wird der Titel aus der HTTP-Methode und dem Endpunkt generiert.
  • description: Das description-Feld der Operation, falls vorhanden.
  • version: Der version-Wert vom übergeordneten Anker oder Tab, falls vorhanden.
  • deprecated: Das deprecated-Feld der Operation. Wenn true, erscheint ein „Veraltet“-Label neben dem Endpunkttitel in der Seitennavigation und auf der Endpunktseite.
Um bestimmte Endpunkte von Ihren automatisch generierten API-Seiten auszuschließen, fügen Sie der Operation in Ihrer OpenAPI-Spezifikation die x-hidden Eigenschaft hinzu.
Es gibt zwei Ansätze, um Endpunktseiten in Ihre Dokumentation aufzunehmen:
  1. Eigene API-Bereiche: Verweisen Sie in Navigationselementen auf OpenAPI-Spezifikationen für dedizierte API-Bereiche.
  2. Ausgewählte Endpunkte: Verweisen Sie in Ihrer Navigation gezielt auf einzelne Endpunkte neben anderen Seiten.

​
Dedizierte API-Abschnitte

Erstellen Sie dedizierte API-Abschnitte, indem Sie einem Navigationselement ein openapi-Feld hinzufügen und keine weiteren Seiten angeben. Alle Endpunkte in der Spezifikation werden einbezogen: 
"navigation": {
  "tabs": [
    {
        "tab": "API Reference",
        "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  ]
}
Sie können mehrere OpenAPI-Spezifikationen in verschiedenen Navigationsbereichen verwenden: 
"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Users",
          "openapi": {
            "source": "/path/to/openapi-1.json",
            "directory": "api-reference"
          }
        },
        {
          "group": "Admin",
          "openapi": {
            "source": "/path/to/openapi-2.json",
            "directory": "api-reference"
          }
        }
      ]
    }
  ]
}
Das Feld directory ist optional und legt fest, wo generierte API-Seiten in Ihrem Docs-Repository gespeichert werden. Wenn nicht angegeben, wird standardmäßig das Verzeichnis api-reference in Ihrem Repository verwendet.

​
Selektive Endpunkte

Wenn Sie genauer steuern möchten, wo Endpunkte in Ihrer Dokumentation erscheinen, können Sie in der Navigation gezielt auf bestimmte Endpunkte verweisen. Dieser Ansatz ermöglicht es, Seiten für API-Endpunkte zusammen mit anderem Inhalt zu erzeugen.

​
Eine OpenAPI-Spezifikation als Standard festlegen

Konfigurieren Sie eine Standard-OpenAPI-Spezifikation für ein Navigationselement. Verweisen Sie anschließend auf spezifische Endpunkte im Feld pages: 
"navigation": {
  "tabs": [
    {
      "tab": "Getting started",
      "pages": [
        "quickstart",
        "installation"
      ]
    },
    {
      "tab": "API reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "api-overview",
        "GET /users",
        "POST /users",
        "guides/authentication"
      ]
    }
  ]
}
Jeder Seiteneintrag, der dem Format METHOD /path entspricht, erzeugt eine API-Seite für diesen Endpunkt unter Verwendung der Standard-OpenAPI-Spezifikation.

​
Vererbung von OpenAPI-Spezifikationen

OpenAPI-Spezifikationen werden entlang der Navigationshierarchie vererbt. Untergeordnete Navigationselemente übernehmen die OpenAPI-Spezifikation ihres übergeordneten Elements, sofern sie nicht eine eigene definieren: 
{
  "group": "API reference",
  "openapi": "/path/to/openapi-v1.json",
  "pages": [
    "overview",
    "authentication",
    "GET /users",
    "POST /users",
    {
      "group": "Orders",
      "openapi": "/path/to/openapi-v2.json",
      "pages": [
        "GET /orders",
        "POST /orders"
      ]
    }
  ]
}

​
Einzelne Endpunkte

Verweisen Sie auf bestimmte Endpunkte, ohne eine Standard-OpenAPI-Spezifikation festzulegen, indem Sie den Dateipfad angeben: 
"navigation": {
  "pages": [
    "introduction",
    "user-guides",
    "/path/to/openapi-v1.json POST /users",
    "/path/to/openapi-v2.json GET /orders"
  ]
}
Dieser Ansatz ist hilfreich, wenn Sie einzelne Endpunkte aus verschiedenen Spezifikationen benötigen oder nur ausgewählte Endpunkte einbinden möchten.

​
MDX-Dateien für API-Seiten erstellen

Um einzelne Endpunktseiten gezielt zu steuern, erstellen Sie für jede Operation eigene MDX-Seiten. So können Sie Seitenmetadaten anpassen, Inhalte hinzufügen, bestimmte Operationen auslassen oder die Reihenfolge der Seiten in Ihrer Navigation auf Seitenebene verändern. Sehen Sie sich ein Beispiel für eine MDX-OpenAPI-Seite von MindsDB an und wie sie in deren Live-Dokumentation dargestellt wird.

​
Dateien manuell angeben

Erstelle für jeden Endpunkt eine MDX-Seite und gib im Frontmatter über das Feld openapi an, welche OpenAPI-Operation angezeigt werden soll. Wenn du eine OpenAPI-Operation auf diese Weise referenzierst, werden Name, Beschreibung, Parameter, Antworten und die API-Spielwiese automatisch aus deinem OpenAPI-Dokument generiert. Wenn du mehrere OpenAPI-Dateien hast, füge den Dateipfad in die Referenz ein, damit Mintlify das richtige OpenAPI-Dokument findet. Wenn du nur eine OpenAPI-Datei hast, erkennt Mintlify sie automatisch.
Diese Vorgehensweise funktioniert unabhängig davon, ob du in deiner Navigation eine Standard-OpenAPI-Spezifikation festgelegt hast. Du kannst jeden Endpunkt aus jeder OpenAPI-Spezifikation referenzieren, indem du den Dateipfad im Frontmatter angibst.
Wenn du eine externe OpenAPI-Datei referenzieren möchtest, füge die URL der Datei deiner docs.json hinzu. 
---
title: "Get users"
description: "Returns all plants from the system that the user has access to"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---
Methode und Pfad müssen exakt der Definition in deiner OpenAPI- Spezifikation entsprechen. Wenn der Endpunkt in der OpenAPI-Datei nicht existiert, bleibt die Seite leer.

​
MDX-Dateien automatisch erzeugen

Verwenden Sie unseren Mintlify-Scraper, um MDX-Seiten für umfangreiche OpenAPI-Dokumente automatisch zu erstellen.
Ihr OpenAPI-Dokument muss gültig sein, sonst werden die Dateien nicht automatisch erzeugt.
Der Scraper erzeugt:
  • Eine MDX-Seite für jede Operation im Feld paths Ihres OpenAPI-Dokuments.
  • Wenn Ihr OpenAPI-Dokument Version 3.1+ ist, eine MDX-Seite für jede Operation im Feld webhooks Ihres OpenAPI-Dokuments.
  • Ein Array mit Navigationseinträgen, das Sie Ihrer docs.json hinzufügen können.
1

`MDX`-Dateien erzeugen.

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
2

Einen Ausgabordner angeben.

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference
Fügen Sie das Flag -o hinzu, um einen Ordner anzugeben, in den die Dateien geschrieben werden. Wenn kein Ordner angegeben ist, werden die Dateien im Arbeitsverzeichnis erstellt.

​
MDX-Dateien für OpenAPI-Schemas erstellen

Sie können für jedes OpenAPI-Schema, das im Feld components.schema eines OpenAPI-Dokuments definiert ist, eigene Seiten erstellen: 
---
openapi-schema: OrderItem
---

​
Webhooks

Webhooks sind HTTP-Callbacks, die Ihre API sendet, um externe Systeme über Ereignisse zu informieren. Webhooks werden in OpenAPI-3.1+-Dokumenten unterstützt.

​
Webhooks in Ihrer OpenAPI-Spezifikation definieren

Fügen Sie Ihrem OpenAPI-Dokument neben dem Feld paths das Feld webhooks hinzu. Weitere Informationen zur Definition von Webhooks finden Sie in der OpenAPI-Dokumentation unter Webhooks.

​
Webhooks in MDX-Dateien referenzieren

Wenn Sie MDX-Seiten für Webhooks erstellen, verwenden Sie webhook statt HTTP-Methoden wie GET oder POST: 
---
title: "Beispiel-Webhook"
description: "Ausgelöst, wenn ein Ereignis eintritt"
openapi: "path/to/openapi-file webhook example-webhook-name"
---
Der Webhook-Name muss genau dem Schlüssel entsprechen, der im Feld webhooks Ihrer OpenAPI-Spezifikation definiert ist.