Die URL verweist auf eine private oder interne Adresse oder leitet dorthin weiter. Verwenden Sie eine Adresse, die für alle im Internet erreichbar ist.
Eine API-Referenz veröffentlichen
Wandeln Sie Ihre OpenAPI- oder GraphQL-Spezifikation in API-Referenzseiten in Ihrem Hilfe-Center um – mit einer Playground-Umgebung, in der Leser echte Anfragen senden können. Leser finden die Vorgänge über dieselbe Suche wie Ihre Artikel, und Ihr KI-Agent kann Fragen dazu beantworten.
Erfordert ein aktives Abonnement oder einen aktiven Testzeitraum.
Spezifikation hinzufügen
Öffnen Sie im Hilfe-Center das Menü zum Hinzufügen eines Abschnitts und wählen Sie API-Referenz erstellen. Wir unterstützen OpenAPI (JSON oder YAML), Swagger 2.0, GraphQL SDL und GraphQL-Introspektions-JSON bis zu einer Größe von 15 MB. Woher die Spezifikation stammt, bestimmt, wie sie aktuell gehalten wird:
Quelle | So bleibt sie aktuell |
|---|---|
Aus GitHub | Wird aktualisiert, wenn ein Push die Spezifikationsdatei im ausgewählten Branch ändert. Erfordert eine verbundene GitHub-Integration. |
Von einer URL | Wir rufen sie alle sechs Stunden erneut ab. Bei einem GraphQL-Endpunkt muss die Introspektion aktiviert sein. |
Datei hochladen | Nicht automatisch. Laden Sie über Spezifikation ersetzen eine neue Datei hoch. |
Verwenden Sie Jetzt aktualisieren, um eine URL- oder GitHub-Quelle sofort abzurufen, und Spezifikation ersetzen, um zu einer anderen Quelle zu wechseln. Um mehrere API-Versionen zu dokumentieren, fügen Sie für jede Version eine eigene Referenz hinzu.
Seiten gestalten
Alle weiteren Einstellungen finden Sie in den Einstellungen der Referenz. Sie müssen die Spezifikation also nicht bearbeiten:
Legen Sie fest, wie die Inhalte in der Seitenleiste angezeigt werden (flach, als Ordner oder als einzelner eingeklappter Eintrag), ordnen Sie Gruppen neu an und weisen Sie ihnen Symbole zu.
Blenden Sie Vorgänge, Schemas oder GraphQL-Typen aus, die Leser nicht benötigen.
Ändern Sie die Zusammenfassung eines Vorgangs, fügen Sie Notizen oder benutzerdefinierte Codebeispiele hinzu. Diese Anpassungen bleiben bei der Aktualisierung der Spezifikation erhalten, solange Methode und Pfad des Vorgangs gleich bleiben.
Codebeispiele können auch aus der Spezifikation selbst stammen: x-codeSamples sowie die SDK-Codeausschnitte in mit Stainless generierten Spezifikationen.
Die Playground-Umgebung
Leser können bei jedem Vorgang auf Ausprobieren klicken oder bei einer GraphQL-Referenz die Playground-Seite verwenden und eine echte Anfrage senden. Die Anfragen laufen über unsere Server statt über den Browser der Leser. Daher ist für Ihre API keine CORS-Konfiguration erforderlich. Sie können nur die in Ihrer Spezifikation aufgeführten Server oder den von Ihnen festgelegten GraphQL-Endpunkt erreichen, niemals jedoch private oder interne Adressen. Schlüssel und Header, die Leser eingeben, werden mit ihrer Anfrage gesendet und nicht zusammen mit der Referenz veröffentlicht.
Veröffentlichen und Zugriff beschränken
Veröffentlichen Sie die Referenz, damit sie in Ihrem Hilfe-Center angezeigt wird, oder aktivieren Sie beim Erstellen Sofort veröffentlichen. Mit API-Referenz zurückziehen nehmen Sie sie offline, wobei Ihre Einstellungen erhalten bleiben. Wenn Sie sie löschen, werden ihre Seiten dauerhaft entfernt.
Für eine Referenz gelten dieselben Zugriffsrechte wie für ihren Abschnitt. Damit sie nur für bestimmte Kunden sichtbar ist, legen Sie sie in einem Abschnitt ab, der auf deren Gruppe beschränkt ist. Weitere Informationen finden Sie unter Inhalte nur bestimmten Lesern anzeigen.
Quellfehler
Host der API-Spezifikations-URL blockiert
Host der API-Spezifikations-URL kann nicht aufgelöst werden
Der Domänenname existiert nicht. Prüfen Sie die URL auf Tippfehler.
Es sind nur HTTP(S)-URLs für API-Spezifikationen zulässig; die URL darf keine eingebetteten Anmeldedaten enthalten
Verwenden Sie eine einfache http://- oder https://-Adresse ohne Benutzername oder Passwort.
Spezifikation konnte nicht von Ihrem Host abgerufen werden oder es gab zu viele Weiterleitungen
Ihr Server hat einen Fehler zurückgegeben oder mehr als fünfmal weitergeleitet. Prüfen Sie, ob die URL weiterhin direkt auf die Spezifikation verweist.
Die URL hat weder ein Spezifikationsdokument noch ein GraphQL-Schema zurückgegeben
Verweisen Sie auf eine OpenAPI-Datei, eine GraphQL-SDL-Datei oder einen GraphQL-Endpunkt, bei dem die Introspektion aktiviert ist.
API-Spezifikation überschreitet die Größenbegrenzung von 15 MB
Verkleinern Sie die Spezifikation, zum Beispiel, indem Sie für jede API eine eigene Referenz erstellen.
Authentifizierung bei GitHub fehlgeschlagen oder die GitHub-Integration kann nicht auf dieses Repository zugreifen
Verbinden Sie GitHub erneut oder gewähren Sie Ihrer GitHub-Integration Zugriff auf dieses Repository und klicken Sie dann auf Jetzt aktualisieren.
Der GitHub-Pfad muss auf eine Datei verweisen, oder die Datei wurde im GitHub-Repository nicht gefunden
Prüfen Sie, ob der Pfad auf die Spezifikationsdatei selbst und nicht auf einen Ordner verweist und ob die Datei im ausgewählten Branch oder Commit vorhanden ist.
Verarbeitung fehlgeschlagen
Wir konnten die Spezifikation nicht lesen. Beheben Sie den Fehler und versuchen Sie es erneut über Spezifikation ersetzen.