Softonic

OpenAPI Pflichtfelder-Prüfung

Schritt 1 / 2
Weiter

Bevor Sie eine API-Beschreibung an einen Kollegen, einen Kunden oder einen Dokumentationsgenerator weitergeben, stellen Sie sicher, dass die Pflichtfelder vorhanden sind. Fügen Sie Ihr Dokument oben ein: Das Tool bestätigt das Versionsfeld, info.title, info.version und paths und listet auf, was fehlt.

So prüfen Sie die Pflichtfelder

  1. 1

    Dokument einfügen

    Fügen Sie Ihre Spezifikation als JSON oder YAML ein, auch wenn sie noch in Arbeit ist.

  2. 2

    Prüfung starten

    Wechseln Sie zum Schritt Ergebnisse. Jedes fehlende Feld erscheint als eigener Fehler.

  3. 3

    Fehlendes ergänzen

    Ergänzen Sie die aufgelisteten Felder in Ihrer Datei mit den Snippets unten.

  4. 4

    Erneut prüfen

    Fügen Sie die aktualisierte Spezifikation ein und führen Sie die Prüfung erneut aus, bis keine Fehler mehr angezeigt werden.

Die vier Pflichtbestandteile

Feld Wo es steht Beispiel
Versionsfeld Oberste Ebene openapi: 3.0.3 oder swagger: "2.0"
info.title Innerhalb von info title: Orders API
info.version Innerhalb von info version: 1.0.0
paths Oberste Ebene paths: mit mindestens Ihrer ersten Route

Der Wert von info.version ist die Version Ihrer eigenen API, nicht die der OpenAPI-Spezifikation. Das wird oft vergessen, weil die Spezifikationsversion bereits oben steht.

Ein Beispiel, bei dem alles fehlt

servers:
  - url: https://api.example.com

Dieses winzige Dokument enthält keinen der Pflichtbestandteile. Der Bericht listet drei Fehler:

Befund Typ
Versionsfeld ‘openapi’ oder ‘swagger’ fehlt. Fehler
Objekt ‘info’ fehlt. Fehler
Objekt ‘paths’ fehlt. Fehler

Wenn das gesamte Objekt info fehlt, meldet das Tool diesen einen Fehler und listet Titel und Version nicht zusätzlich einzeln auf. Ergänzen Sie info mit beiden Feldern, dann zeigt der nächste Durchlauf an, falls noch etwas fehlt.

Startgerüst

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders

Dieses Gerüst besteht alle Prüfungen auf Pflichtfelder. Ersetzen Sie die Namen durch Ihre eigenen und bauen Sie von dort aus weiter. Antworten, Schemas und Sicherheit gehören nicht zu dieser Prüfung.

Wann Sie diese Prüfung ausführen sollten

Führen Sie sie aus, wenn Sie eine Spezifikation von Grund auf neu beginnen, nachdem Sie sie aus dem Code generiert haben, und bevor Sie sie an jemanden senden, der sie in ein anderes Tool importiert. Viele Importer brechen beim ersten fehlenden Pflichtfeld mit einer kurzen Meldung ab. Wer alle in einem Durchgang findet, spart sich mehrere Schleifen. Auch für Einsteiger ist die Prüfung hilfreich, da sie beim Skizzieren einer API oft info.version vergessen oder paths weglassen.

Nach bestandenen Pflichtfeldern lohnen sich als Nächstes eine kurze description unter info, ein Eintrag in servers und eine operationId für jede Operation. Diese werden hier nicht geprüft, machen die Spezifikation aber lesbarer und erleichtern die Erzeugung von Client-Code.

Häufig gestellte Fragen

Nein. Das Feld openapi gibt an, welche Version der Spezifikation Sie verwenden. info.version ist die Version Ihrer eigenen API, zum Beispiel 1.0.0.

Der Schlüssel muss als Objekt vorhanden sein. Diese Prüfung verlangt aber keine Routen darin. Fügen Sie vor der Veröffentlichung echte Routen hinzu.

Die Prüfungen für Titel und Version laufen nur, wenn das Objekt info existiert. Ergänzen Sie es und führen Sie die Prüfung erneut aus, um zu sehen, ob seine Felder vollständig sind.

Nein. Hier sind nur das Versionsfeld, info, title, version und paths erforderlich. Details auf Operationsebene werden nicht untersucht.

Verwandte Tools

Zufallsbuchstaben-Generator

Erzeugen Sie zufällige A-Z-Buchstaben. Wählen Sie Anzahl, Großschreibung, Kleinschreibung oder gemischte Schreibweise für Spiele, Aufgaben und Unterricht.

FPS-Zähler

Browser-FPS mit requestAnimationFrame messen: Glättung, minimale und maximale Bildrate, Warnschwelle und optionales Diagramm. Läuft lokal, ohne Upload und ohne API.

XSD-Validator

Validieren Sie ein XML-Dokument gegen ein XSD-Schema und melden Sie Element- und Typfehler mit genauen Zeilennummern.

HTML-Zeichenreferenz

Durchsuchbare Liste von HTML-Entitäten, ihren benannten und numerischen Codes sowie eine Ein-Klick-Kopie für Sonderzeichen und Symbole.

CSS-Loader-Generator

Erstellen Sie einen kreisförmigen Spinner in reinem CSS: Durchmesser, Rahmenstärke, Akzentfarbe und Rotationsgeschwindigkeit festlegen, live ansehen und den fertigen CSS-Code kopieren. Kein SVG, kein JavaScript.

Markdown-Spickzettel

Praktische Markdown-Referenz mit echten Vorschauen und kopierfertigen Beispielen für Überschriften, Listen, Tabellen, Code, Links, Bilder und GFM-Syntax.

Tool in anderen Sprachen verfügbar

Anleitungen und Anwendungsfälle