So generieren Sie ein JSON-Schema aus der Swagger-API-Deklaration

74

Ich habe die Swagger-API-Deklaration für Dienste, die Swagger v 1.2 verwenden

Mein ursprüngliches Gefühl bei Swagger war, dass es dem JSON-Schema (Entwurf 3 und kürzlich Entwurf 4) sehr nahe kommt und es relativ einfach sein soll, ein JSON-Schema für Anforderungs- und Antwortobjekte zu generieren.

Während ein Teil von Swagger JSON-Schemastrukturen wiederverwendet, stellte sich heraus, dass nur eine Teilmenge von Features verwendet wird und dass eine eigene Vererbung in Models (using subTypesund discriminator) eingeführt wird.

Frage: Gibt es ein vorhandenes Projekt oder einen Code, der aus der Swagger-API-Deklaration ein verwendbares JSON-Schema generieren kann ?

Optimal JSON Schema Draft 4 und mit Python (aber ich werde gerne etwas finden).

swagger jsonschema Jan Vlcinsky
quelle

Antworten:

79

Nachdem ich länger mit der Verwendung von Swagger für die Angabe der REST-API und deren Wiederverwendung in verwandten Testsuiten gekämpft habe, werde ich meine eigenen Erfahrungen damit teilen (Beantwortung meiner eigenen Frage).

Swagger unterstützt nur eine Teilmenge von JSON Schema Draft 4

Die Spezifikation der Zustände Swagger 1.2 und 2.0 unterstützt nur eine Teilmenge von JSON Schema Draft 4 (s. Hier ). Das bedeutet, dass:

  • Man kann sich nicht darauf verlassen, dass jedes gültige JSON-Schema vollständig von Swagger unterstützt werden kann.
  • In Bezug auf XML unterstützt Swagger nur die kanonische Darstellung einer Teilmenge von JSON-Strukturen, die von JSON Schema Draft 4 bereitgestellt werden.

Mit anderen Worten:

  • Swagger (1.2 und 2.0) unterstützt nicht die Verwendung vieler JSON-Strukturen, die für JSON Schema Draft 4 gültig sind (dasselbe gilt für Draft 3).
  • Swagger unterstützt keine allgemeinen XML-Datenstrukturen, nur sehr eingeschränkte Strukturen sind zulässig.

In der Praxis können Sie nicht mit dem Entwerfen Ihrer Daten in JSON oder XML beginnen. Bei Swagger müssen Sie mit Swagger beginnen und enden.

Das Abrufen des JSON-Schemas ist theoretisch möglich, aber nicht einfach

Ich habe einige Zeit damit verbracht, eine Bibliothek zu codieren, die die Swagger-API-Spezifikation übernimmt und JSON Schema Draft 4 erstellt. Ich habe aus mehreren Gründen aufgegeben:

  • es war überhaupt nicht einfach
  • Ich war enttäuscht, dass ich nur einen Teil dessen verwenden kann, was JSON Schema bietet. Wir hatten bereits einige JSON-Nutzdaten vorgeschlagen und mussten damit beginnen, sie an die Anforderungen des Swagger-Spezifikationsframeworks anzupassen.

Abgesehen davon, dass die Benutzeroberfläche zum Anzeigen und Testen der API wirklich gut aussieht (ja, alle sind sich einig, sie ist optisch sehr ansprechend), fand ich es seltsam, dass ein Spezifikationsframework es uns nicht erlaubt, das zu verwenden, was wir wollen, sondern unerwartete Einschränkungen hinzufügt zu unserem Design.

Wenn Sie vollständige Unterstützung für JSON- oder XML-Schemas wünschen, verwenden Sie RAML

Bei der Untersuchung anderer API-Spezifikations-Frameworks habe ich RAML gefunden. Da es von Grund auf durch die Unterstützung von JSON Schema Draft 3/4- oder W3C XML Schema 1.0-Datenstrukturen erstellt wurde, war die Erfahrung ausgezeichnet - da die Struktur meiner Nutzdaten entworfen wurde, konnte ich die API-Spezifikation sehr schnell erstellen und nach Validierung realer Anforderungen Die Reaktion auf definierte Schemata war sehr einfach, da die Schemata wesentliche Bestandteile der Spezifikation sind, ohne sie einzuschränken.

RAML war zu diesem Zeitpunkt auf Version 0.8 (Version 1.0 wurde noch nicht veröffentlicht).

Die Korrektur der Frage führt zu einer echten Lösung

Gute Frage macht die Hälfte der Lösung. Meine Frage war falsch, da sie meine wirklichen Erwartungen nicht erfüllte. Die korrigierte Frage wäre:

Welches Spezifikationsframework und welche Technik zu verwenden ist, um die REST-API unter Verwendung von Nutzdaten anzugeben, die durch ein beliebiges JSON-Schema Draft 4 oder W3C XML Schema 1.0 definiert sind.

Meine Antwort auf eine solche Frage wäre:

  1. Entwerfen Sie Ihre Nutzdaten in JSON Schema Draft 4 oder W3C XML Schema
  2. Beschreiben Sie Ihre REST-API mithilfe von RAML (derzeit v0.8).

Möglicherweise können andere Spezifikationsframeworks verwendet werden, aber Swagger (weder v1.2 noch v2.0) ist definitiv nicht der Fall. Abgesehen davon, dass es wirklich viele Funktionen bietet (Codegenerierung, sehr gut aussehende Dokumentation der API und vieles mehr), kann die oben genannte aktualisierte Frage einfach nicht gelöst werden.

Jan Vlcinsky
quelle
Es gibt einige Swagger-zu-RAML-Konverter da draußen. @ jan-vlcinsky denkst du, das könnte für "einfache" Schemata funktionieren? swagger-> RAML->JSON Schema
Webwurst
@ Webwurst klingt vielversprechend. Kennen Sie ein Tool, das RAML in JSON-Schema konvertiert? Oder erstellt die Konvertierung in RAML bereits das JSON-Schema für die Elemente? Wie auch immer, meine Hauptprobleme mit Swagger waren falsche Erwartungen, dass ich in Swagger alles ausdrücken kann, was das JSON-Schema erlaubt, und dies stimmte nicht.
Jan Vlcinsky
Das einzige Problem ist, dass die Community rund um RAML immer noch nicht populär genug ist. Und genau wie Sie gesagt haben, kann ich, wenn Swagger ein vollständiges JSON-Schema zulässt, ein Dutzend Code in pyswagger entfernen, indem ich sie durch einen besseren Python-Parser ersetze.
Mission.liao
Angenommen, Ihre Daten werden im JSON-Schema (nicht im XML-Schema) modelliert. Was sind die Hauptvorteile der Verwendung von RAML gegenüber JSON Hyper-Schema zum Definieren Ihrer API? Es scheint, als würde die Liste der fehlenden Funktionen einen Ausgangspunkt für JSON Hyper-Schema Draft-5 bilden (vorausgesetzt, hinter diesem Vorschlag steht eine Community).
Kerlyn
10

Es gibt ein Python-Tool mit dem Namen openapi2jsonschema . Sie können es einfach mit installieren pip.

Die Readme-Datei für openapi2 zeigt die einfachste Verwendung:

openapi2jsonschema https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json

Hoffe das hilft.

Akash Masand
quelle
Dies funktioniert auch gut für Offline-Yaml-Open-API-Spezifikationen.
Len
6

Ich habe gerade ein Tool geschrieben, das pyswagger Ihren Anforderungen entspricht.

Es lädt die Swagger-API-Deklaration und kann Python-Objekte in / von Swagger-Grundelementen konvertieren . Stellen Sie außerdem eine Reihe von Client-Implementierungen bereit (einschließlich Anforderungen und tornado.httpclient.AsyncHTTPClient ), mit denen Anforderungen direkt an den Swagger-fähigen Dienst gesendet werden können.

Dieses Tool löst in der Regel das erste Problem, auf das ich beim Anpassen von Swagger in Python gestoßen bin, und ist jetzt noch ziemlich neu. Willkommen für jeden Vorschlag.

mission.liao
quelle
@missionliao Der erste Eindruck ist sehr gut. Innerhalb weniger Wochen werde ich kommen, um es genauer zu untersuchen, meine Bewerbung (derzeit SwaggerProxy) zu veröffentlichen, und wir können uns unseren Bemühungen anschließen. Einige der in Ihrer Lösung sichtbaren Entwurfsentscheidungen sind denen, die ich ebenfalls getroffen habe, sehr ähnlich. Dies ist ein vielversprechendes Signal.
Jan Vlcinsky
1

Ich hatte einige Erfolge damit:

swagger.yaml -> proto -> jsonschema

Ich habe openapi2proto verwendet, um Protodateien aus Swagger yaml zu generieren, und dann protoc-gen-jsonschema, um daraus die JSONSchemas zu generieren. Es ist gut genug, um ein typisiertes JSONSchema zu erhalten, aber proto3 unterstützt keine "erforderlichen" Typen, sodass Sie dies verpassen.

Chrusty
quelle