Swagger 2.0 Validator

Was bei Swagger 2.0 als bestanden gilt

Bei einer 2.0-Datei wird die Versionsprüfung durch einen Schlüssel swagger auf oberster Ebene erfüllt. Das Tool prüft nicht, ob der Wert "2.0" ist, und erkennt daher keine falsche Nummer. Über die Version hinaus braucht es info.title, info.version und ein paths-Objekt.

Felder, die speziell zu Swagger 2.0 gehören, etwa host, basePath, schemes, definitions und securityDefinitions, werden nicht untersucht. Ein fehlendes host oder ein kaputter definitions-Block wird nicht gemeldet.

Ein Beispiel

{
  "swagger": "2.0",
  "info": { "title": "Shop API", "version": "1.0" },
  "paths": {
    "/products": {
      "get": { "summary": "List products" },
      "x-internal": true
    }
  }
}

Das Versionsfeld, info und paths sind alle vorhanden, es gibt also keine Fehler. Der Bericht zeigt eine Warnung:

Das Dokument gilt trotzdem als gültig, weil Warnungen die Gültigkeit nicht blockieren. Herstellererweiterungen wie x-internal sind in Swagger 2.0 zulässig, Sie können sie also stehen lassen.

Von 2.0 migrieren

Wenn Sie auf OpenAPI 3.x umstellen wollen, können Sie die konvertierte Datei in dasselbe Feld einfügen und die Ergebnisse vergleichen. Die Prüfung ist dieselbe, nur ersetzt das Feld openapi das Feld swagger. Für die eigentliche Migration brauchen Sie einen vollständigen Konverter und Linter, denn dieses Tool übersetzt die Einstellungen definitions und host nicht.

Wann eine schnelle Prüfung reicht

Swagger-2.0-Definitionen bleiben oft jahrelang in Repositories und werden von Hand bearbeitet. Eine schnelle Strukturprüfung hilft, wenn Sie eine übernommen haben, wenn ein Tool sie nicht laden will und Sie ein fehlendes Feld vermuten oder wenn Sie zwei Dateien zusammenführen und sicher sein wollen, dass das Ergebnis seine Abschnitte info und paths behält. Für die vollständigen Regeln von 2.0, einschließlich definitions und Sicherheitseinstellungen, verwenden Sie anschließend einen eigenen Linter.

Denken Sie daran, dass ein sauberer Bericht nur eine Aussage über die Struktur ist. Operationen ohne Antworten, falsche Parametertypen und nicht aufgelöste Verweise liegen außerhalb dieser Prüfung. Testen Sie die Datei deshalb auch in Ihrem Dokumentations- oder Code-Generator.