Startseite › Entwickler-Tools › <strong>Bearbeite links</strong>: Die Dokumentation rechts aktualisiert sich beim Tippen, und Probleme werden am Rand hervorgehoben.

<strong>Bearbeite links</strong>: Die Dokumentation rechts aktualisiert sich beim Tippen, und Probleme werden am Rand hervorgehoben.

Schreib oder füge links eine Spezifikation für OpenAPI 3.0, 3.1 oder Swagger 2.0 ein und erhalte rechts eine Live-API-Dokumentation: Endpunkte nach Tag gruppiert, Parameter, Request- und Response-Schemas mit generiertem Beispiel-JSON und eine Problemliste mit anklickbaren Zeilennummern. Dein Entwurf wird automatisch in diesem Browser gespeichert.

Zuletzt aktualisiert:

Dein Entwurf wird automatisch nur in diesem Browser gespeichert (lokaler Speicher) und nie hochgeladen. Klick auf den Link Bearbeiten eines Endpunkts, um zu seinem YAML zu springen. Tab rückt um zwei Leerzeichen ein; drück Esc und dann Tab, um den Editor zu verlassen.

Anzeige
Anzeige

Anleitung: <strong>Bearbeite links</strong>: Die Dokumentation rechts aktualisiert sich beim Tippen, und Probleme werden am Rand hervorgehoben.

  1. Starte mit einer Vorlage (das Beispiel „Task Tracker 3.1“ wird zuerst geladen), öffne deine eigene .yaml-/.json-Datei oder füge eine Spezifikation ein.
  2. Edit on the left: the documentation on the right refreshes as you type, and problems are highlighted in the gutter.
  3. Füge Snippets ein für einen neuen Pfad, eine Operation, einen Query-Parameter, ein Schema oder ein Security-Scheme; sie werden automatisch im richtigen Abschnitt platziert.
  4. Prüfe den Tab „Probleme“ und klick auf einen Eintrag, um zu seiner Zeile zu springen; nutze „Bearbeiten“ an einem Endpunkt, um sein YAML zu finden.
  5. Lade die fertige Spezifikation als YAML oder JSON herunter oder kopiere sie in die Zwischenablage.

Aufbau eines OpenAPI-Dokuments

Jedes OpenAPI-3-Dokument besteht aus denselben wenigen Abschnitten auf oberster Ebene. Wenn du weißt, wohin jedes Teil gehört, kannst du die Problemliste des Editors viel leichter abarbeiten:

AbschnittPflicht?Was hineingehört
openapiJaDie Spezifikationsversion als String, z. B. 3.1.0 (Swagger 2.0 verwendet swagger: "2.0").
infoJatitle und version (deiner API), optional Beschreibung, Kontakt und Lizenz.
serversNoBasis-URLs, optional mit {variables} wie Umgebung oder Region.
pathsJa in 3.0, optional in 3.1Jede URL-Vorlage (/tasks/{taskId}) mit ihren Operationen: get, post, put, patch, delete…
componentsNoWiederverwendbare schemas, parameters, responses, requestBodies und securitySchemes, referenziert mit $ref.
securityNoStandard-Authentifizierung für alle Operationen; Operationen können sie überschreiben (verwende security: [] für öffentliche Endpunkte).
tagsNoNamen und Beschreibungen, mit denen Operationen in der Dokumentation gruppiert werden.

Tipps zum Schreiben von Spezifikationen von Hand

  • Setze Statuscodes und Versionen in Anführungszeichen: Schreib '200': und version: "1.0". Ohne Anführungszeichen liest YAML sie als Zahlen.
  • Definiere Schemas einmal: Leg Modelle unter components/schemas an und referenziere sie, damit Request, Response und Dokumentation konsistent bleiben.
  • Nutze allOf für „Create“- und „Read“-Modelle: Ein NewTask-Schema plus Task = allOf [NewTask, {id, createdAt}], wie in der Vorlage, vermeidet doppelte Felder.
  • Gib jeder Operation eine operationId: Codegeneratoren nutzen sie als Methodennamen, halte sie also eindeutig und in camelCase.
  • Markiere vom Server erzeugte Felder als readOnly (IDs, Zeitstempel), damit Clients wissen, dass sie sie nicht senden sollen; der Beispielgenerator folgt derselben Regel für writeOnly-Felder.
  • Beschreibe Fehler: Füge 4XX-Responses oder eine gemeinsame default-Fehlerresponse hinzu, damit Client-Entwickler wissen, wie Fehler aussehen.

Du willst nur eine vorhandene Datei prüfen? Der OpenAPI-Validator liefert einen vollständigen Bericht und einen dereferenzierten Download. Um eine fertige Spezifikation mit Suche und Swagger UI zu durchsuchen, nutze den OpenAPI-Viewer.

Häufige Fragen

Wo wird meine Spezifikation gespeichert?

Nur im lokalen Speicher deines Browsers auf diesem Gerät, sodass sie noch da ist, wenn du zurückkommst. Nichts wird auf einen Server hochgeladen. Wenn du Websitedaten löschst oder ein privates Fenster nutzt, geht der Entwurf verloren, lade wichtige Spezifikationen also herunter.

Ist das dasselbe wie der Swagger Editor?

Er deckt denselben Arbeitsablauf im Alltag ab (YAML bearbeiten, gerenderte Doku und Fehler nebeneinander sehen), ist aber ein schlankes, unabhängiges Tool. Er sendet keine Testanfragen an deine API; dafür exportierst du die Spezifikation und nutzt einen API-Client oder probierst den API Request Tester.

Sollte ich OpenAPI in YAML oder JSON schreiben?

Beide beschreiben genau dasselbe Dokument. YAML ist von Hand leichter zu lesen und zu schreiben und erlaubt Kommentare; JSON lässt sich im Code leichter erzeugen und parsen. Der Editor wandelt mit einem Klick zwischen beiden um (Kommentare werden nicht nach JSON übernommen).

Welche OpenAPI-Version sollte eine neue API verwenden?

OpenAPI 3.1 ist die aktuelle Version und gleicht Schemas an JSON Schema 2020-12 an (zum Beispiel type: [string, 'null'] statt nullable). Verwende 3.0.3, wenn dein Codegenerator oder Gateway 3.1 noch nicht unterstützt; Swagger 2.0 ist nur für ältere Tools gedacht.

Wie werden die Beispiel-Payloads erstellt?

Für jedes Request- und Response-Schema erzeugt der Editor Beispiel-JSON aus vorhandenen example-, default- oder enum-Werten und sonst aus Typ und Format (zum Beispiel ein date-time-String oder eine UUID). writeOnly-Eigenschaften werden in Beispielen weggelassen.

Unterstützt er $ref und allOf?

Ja. Interne Referenzen wie #/components/schemas/Task werden in der Vorschau aufgelöst, allOf-Schemas werden zu einer Eigenschaftsliste zusammengeführt, und oneOf/anyOf-Alternativen werden aufgelistet. Rekursive Schemas werden einmal mit einer Rekursionsmarkierung angezeigt.

Kann ich ihn offline nutzen?

Nachdem die Seite geladen ist, funktionieren Bearbeitung, Vorschau und Validierung ohne Verbindung. Der YAML-Parser wird beim ersten Mal von einem CDN geladen; JSON-Spezifikationen funktionieren auch, wenn er nicht geladen werden kann.

Werden alle Tools auf FreeToolCabin auf Qualität und Genauigkeit getestet?

Ja. Jedes Tool auf der Website durchläuft automatische Tests in echten Browsern, die prüfen, ob das Ergebnis stimmt und keine Fehler auftreten. Wenn du einen Fehler findest oder einen Vorschlag hast, schreib uns an [email protected] – wir sehen es uns an.

Ähnliche Tools

Alle Code-Generatoren & Builder ansehen →