Spezifikationen mit dem Spezifikationseditor erstellen

Sie sehen sich die Dokumentation zu Apigee Edge an.
Sehen Sie sich die Apigee X-Dokumentation an. info

Mit dem Spezifikationseditor können Sie OpenAPI-Spezifikationen erstellen und validieren, ohne Code schreiben zu müssen.

Auf den Spezifikationseditor zugreifen

Öffnen Sie eine OpenAPI-Spezifikation im Spezifikationseditor, wie in den folgenden Abschnitten beschrieben:

Die folgende Abbildung zeigt die Spezifikation für die Petstore API, die im Spezifikationseditor geöffnet ist:

Wie in der vorherigen Abbildung hervorgehoben, können Sie mit dem Spezifikationseditor Folgendes tun:

  • Erstellen Sie im linken Bereich eine OpenAPI-Spezifikation, um Ihre API im JSON- oder YAML-Format zu modellieren.
  • Im rechten Bereich wird die automatisch generierte API-Dokumentation angezeigt.
  • Prüfen Sie Ihre Spezifikation während der Eingabe anhand des OpenAPI-Spezifikationsstandards.
  • Speichern Sie die OpenAPI-Spezifikation oder schließen Sie die Spezifikation und brechen Sie die Änderungen ab.

Hilfe zu JSON und YAML

JSON (JavaScript Object Notation) ist ein einfaches Datenaustauschformat, das zum Darstellen einfacher Datenstrukturen und assoziativer Arrays verwendet wird. Weitere Informationen finden Sie unter https://www.json.org.

YAML (YAML Ain't Markup Language) ist ein Standard für die Datenserialisierung/-darstellung, der eine Syntax bietet, die Datenstrukturen wie Listen, assoziative Arrays und Skalare zuordnen kann. Weitere Informationen finden Sie unter https://yaml.org.

Sowohl JSON als auch YAML sind maschinenlesbar, aber auch für Menschen leicht lesbar und verständlich. In der folgenden Abbildung werden zwei kurze Auszüge aus derselben OpenAPI-Spezifikation verglichen, die in JSON und YAML geschrieben wurden:

JSON und YAML im Vergleich

Spezifikation validieren

Im Spezifikationseditor wird Ihre OpenAPI-Spezifikation anhand des OpenAPI-Spezifikationsstandards validiert. Wenn beim Tippen Fehler in Ihrer OpenAPI-Spezifikation auftreten, wird im Spezifikationseditor oben im rechten Bereich das Dialogfeld „Fehler“ angezeigt. Dort finden Sie weitere Informationen zu den Fehlern und den zugehörigen Zeilennummern, damit Sie sie leicht korrigieren können.

Fehler

Spezifikation speichern

Wenn Sie eine OpenAPI-Spezifikation speichern möchten, klicken Sie in der oberen Navigationsleiste auf Speichern.

Wenn Sie die Spezifikation zum ersten Mal speichern, werden Sie aufgefordert, einen Dateinamen einzugeben. Wenn Sie keinen Dateinamen angeben, wird standardmäßig „Ohne Titel“ verwendet. Sie können sie später umbenennen.

Spezifikation schließen

Wenn Sie eine OpenAPI-Spezifikation schließen möchten, ohne Ihre Änderungen zu speichern, klicken Sie in der oberen Navigationsleiste auf Abbrechen. Sie werden zur Liste der Spezifikationen zurückgeleitet.