Mintlify transformiert OpenAPI 3.0- und 3.1-Spezifikationen (im JSON- oder YAML-Format) in moderne, interaktive API-Dokumentationen. Statt Parameter, Header und Payload-Schemata manuell in Markdown-Tabellen zu pflegen, können Entwicklungs- und Dokumentationsteams ihre Spezifikationsdatei direkt importieren. Mintlify analysiert die Endpunkte automatisiert, erzeugt Codebeispiele für gängige Programmiersprachen und stellt einen interaktiven API-Playground bereit, mit dem Entwickler HTTP-Anfragen unmittelbar im Browser ausführen können.
Die Plattform folgt einem Docs-as-Code-Paradigma: Die OpenAPI-Definition wird gemeinsam mit den Inhalten in einem Git-Repository verwaltet. Die globale Strukturierung erfolgt über eine zentrale Konfigurationsdatei (docs.json, bzw. mint.json in älteren Setups). Teams haben die Wahl zwischen zwei Vorgehensweisen: der vollautomatischen Referenzerstellung ohne manuellen Pflegeaufwand oder der gezielten Verknüpfung von OpenAPI-Routen mit benutzerdefinierten MDX-Seiten, um Endpunkte mit Leitfäden, Hinweisen und Architekturdiagrammen zu ergänzen.
Voraussetzungen und Spezifikationsanforderungen
Bevor Sie Mintlify konfigurieren, sollten Sie sicherstellen, dass Ihre Spezifikation die technischen Kriterien erfüllt:
- Unterstützte Spezifikationsversionen: Mintlify unterstützt nativ die OpenAPI-Spezifikation (OAS) 3.0 und 3.1. Liegt Ihre Definition noch im Swagger-2.0-Format vor, muss sie vorab nach OpenAPI 3.0 migriert werden.
- Dateiformate: Es werden standardmäßige JSON- (
.json) und YAML-Dateien (.yamloder.yml) unterstützt. - Einschränkungen bei Referenzen ($ref): Interne Verweise innerhalb desselben Dokuments (beispielsweise
$ref: '#/components/schemas/User') werden nahtlos aufgelöst. Externe Referenzen auf separate Dateien werden jedoch nicht unterstützt. Wenn Ihre Spezifikation auf mehrere Schema-Dateien aufgeteilt ist, muss sie vor dem Import über Bundling-Tools (wie Redocly CLI oder@apidevtools/swagger-cli) in eine einzelne Datei zusammengeführt werden.
Schritt 1: Platzierung der OpenAPI-Spezifikationsdatei
Sie können Ihre Spezifikation entweder direkt im lokalen Repository ablegen oder über eine externe HTTPS-URL einbinden:
-
Lokales Repository (Empfohlen): Legen Sie die Spezifikationsdatei direkt in Ihrem Dokumentations-Repository ab. Typische Speicherorte sind das Stammverzeichnis des Projekts (z. B.
openapi.jsonoderopenapi.yaml) oder ein eigenes Verzeichnis für Schnittstellen (wieapi-reference/openapi.jsonoderspecs/v1.yaml). -
Gehostete Remote-URL: Erzeugt Ihre Backend-CI/CD-Pipeline automatisch eine aktuelle OpenAPI-Datei auf einem Objektspeicher oder CDN, können Sie eine direkte HTTPS-URL hinterlegen (z. B.
https://api.example.com/specs/openapi.json). Für Produktions-Builds müssen Remote-Spezifikationen zwingend über HTTPS ausgeliefert werden.
Schritt 2: Navigation in docs.json konfigurieren
Um die API-Referenz in der linken Seitenleiste anzuzeigen, wird die Datei im navigation-Objekt der docs.json verknüpft.
Ansatz A: Vollautomatische Referenzerstellung
Wenn Mintlify alle Pfade automatisch einlesen, anhand der OpenAPI-tags gruppieren und entsprechende Seiten generieren soll, verweisen Sie direkt im Navigationstab oder in einer Gruppe auf die Datei:
{
"$schema": "https://mintlify.com/docs.json",
"name": "Acme API Docs",
"navigation": {
"tabs": [
{
"tab": "Leitfäden",
"groups": [
{
"group": "Erste Schritte",
"pages": ["introduction", "quickstart"]
}
]
},
{
"tab": "API Reference",
"openapi": "openapi.json"
}
]
}
}
Bei dieser Konfiguration liest Mintlify alle Routen unter paths aus, ermittelt HTTP-Methoden, Kurzbeschreibungen, Parameter sowie Antwort-Schemata und baut die Navigationsstruktur vollständig ohne manuelle MDX-Dateien auf.
Verwaltung mehrerer Spezifikationen
Umfasst Ihre Plattform mehrere Mikrodienste oder Versionen, übergeben Sie ein Array von Dateipfaden:
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": [
"specs/v1/auth.json",
"specs/v1/billing.json",
"specs/v2/core.json"
]
}
]
}
}
Schritt 3: Granulare Dokumentation mit MDX-Seiten
Die automatische Generierung ist effizient, doch Technische Redakteure möchten Endpunkte häufig mit betrieblichen Voraussetzungen, Warnhinweisen zu Rate-Limits oder Ablaufdiagrammen anreichern. Mintlify erlaubt es, MDX-Seiten über das Frontmatter direkt mit einzelnen Endpunkten zu verknüpfen.
1. MDX-Datei an einen Endpunkt binden
Erstellen Sie eine MDX-Datei (z. B. api-reference/users/create.mdx) und deklarieren Sie Methode und Pfad im openapi-Frontmatter-Feld:
---
title: "Benutzer anlegen"
sidebarTitle: "Benutzer anlegen"
description: "Registriert ein neues Benutzerkonto innerhalb der Organisation"
openapi: "POST /v1/users"
---
## Übersicht
Bevor Sie diesen Endpunkt aufrufen, stellen Sie sicher, dass Ihre Anwendung über den OAuth-Scope `users:write` verfügt.
<Warning>
Die E-Mail-Adresse muss organisationsweit eindeutig sein. Bei Duplikaten antwortet die API mit dem Fehlercode `409 Conflict`.
</Warning>
## Webhook-Benachrichtigungen
Nach erfolgreicher Erstellung sendet das Acme-System automatisch ein `user.created`-Ereignis an Ihre konfigurierten Webhook-Ziele.
Mintlify extrahiert den Endpunkt POST /v1/users aus Ihrer Spezifikation, bettet den interaktiven Request-Builder und die Parameterübersicht in die Seite ein und rahmt sie nahtlos mit Ihren MDX-Inhalten ein.
Werden mehrere Spezifikationsdateien verwendet, stellen Sie den Dateinamen voran:
---
title: "Benutzer anlegen"
openapi: "specs/v1/auth.json POST /v1/users"
---
2. MDX-Vorlagen im Batch mit dem Scraper erzeugen
Möchten Sie für zahlreiche bestehende Endpunkte individuelle MDX-Dateien als editierbare Ausgangsbasis generieren, nutzen Sie das offizielle Scraping-Werkzeug:
npx @mintlify/scraping@latest openapi-file ./openapi.json -o api-reference
Der Befehl verarbeitet Ihre Spezifikation und legt im Ordner api-reference automatisch alle MDX-Dateien mit passenden Frontmatter-Eigenschaften an.
Schritt 4: Konfiguration des interaktiven API-Playgrounds
Der Playground ermöglicht es Entwicklern, Anfragen direkt aus der Dokumentation heraus auszuführen. Für einen fehlerfreien Betrieb sind folgende Aspekte wesentlich:
1. Basis-Server-URLs festlegen
Mintlify übernimmt die Ziel-URLs unmittelbar aus dem servers-Array der OpenAPI-Spezifikation:
servers:
- url: https://api.example.com/v1
description: Produktionsumgebung
- url: https://staging.api.example.com/v1
description: Staging-Sandbox
Sind mehrere Server hinterlegt, zeigt der Playground ein Dropdown-Menü zur einfachen Auswahl der Zielumgebung.
2. Authentifizierung und Test-Tokens
Definieren Sie Autorisierungsschemata unter components.securitySchemes. Mintlify erzeugt daraufhin passende Eingabefelder (Bearer Token, API-Key, Basic Auth):
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Geben Sie Ihren API-Zugriffstoken ein
security:
- bearerAuth: []
Um Testaufrufe in Demoumgebungen zu beschleunigen, können Sie über die Erweiterung x-default vorgefertigte Testschlüssel bereitstellen:
{
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"x-default": "demo_pk_live_testing123"
}
}
}
}
3. CORS-Anforderungen (Cross-Origin Resource Sharing)
Da Anfragen aus dem Playground direkt im Webbrowser des Nutzers generiert werden, muss das Backend korrekte CORS-Header zurücksenden:
Access-Control-Allow-Origin: *(oder die Domain Ihrer Dokumentationsseite)Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONSAccess-Control-Allow-Headers: Authorization, Content-Type, X-API-Key
Verweigert das Backend Preflight-Anfragen (OPTIONS), schlagen Anfragen im Playground fehl, selbst wenn sie lokal über curl erfolgreich sind.
Schritt 5: Spezifikationsanpassung mit OpenAPI Overlays
Oftmals enthalten aus Programmcode generierte Spezifikationen interne Routen oder für Anwender ungeeignete technische Formulierungen. Um den Originalcode nicht manipulieren oder eine separate Spezifikationskopie verwalten zu müssen, unterstützt Mintlify die OpenAPI Overlay Specification (v1.1.0).
In einer Overlay-Datei definieren Sie JSONPath-gestützte Operationen (update, remove, copy):
overlay: 1.1.0
info:
title: Anpassungen für die öffentliche Dokumentation
version: 1.0.0
extends: ./openapi.json
actions:
- target: $.info.description
update: "Willkommen in der Acme-Entwicklerdokumentation. Testen Sie unsere Endpunkte live."
- target: $.paths['/internal/system-health']
remove: true
- target: $.paths['/v1/billing'].post.summary
update: "Wiederkehrendes Abonnement erstellen"
Verknüpfen Sie das Overlay anschließend in Ihrer docs.json:
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": {
"source": "openapi.json",
"overlays": ["overlays/public-filter.yaml"]
}
}
]
}
}
Mintlify wendet diese Anpassungen während des Dokumentations-Builds verlustfrei an: Interne Pfade werden ausgefiltert und Texte verfeinert, während die Spezifikationsdatei im Quellcode unverändert bleibt.
Schritt 6: Lokale Vorschau und CI/CD-Validierung
Testen Sie Ihre Änderungen vor der Bereitstellung auf Ihrem Entwicklungssystem mit der Mintlify CLI:
-
Entwicklungsserver starten:
npm i -g mintlify mint dev -
Lokal bereitgestellte Schemata testen: Wird Ihre Spezifikation von einem lokalen Prozess serviert (z. B.
http://localhost:8000/openapi.json), starten Sie die CLI mit entsprechender Berechtigung:mint dev --local-schema -
Strenge Validierungsprüfungen: Führen Sie Prüfungen auf fehlerhafte Referenzen oder fehlende Antworten durch:
mint validate -
Einbindung in CI/CD-Pipelines: Integrieren Sie
mint validatein Ihre GitHub Actions oder GitLab CI. Ändern Entwickler die Spezifikation, wird die Validität automatisch überprüft, bevor fehlerhafte Dokumentationen online gehen.