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

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

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

In Swagger 1.2 und 2.0 wird nur eine Teilmenge von JSON Schema Draft 4 unterstützt (s. hier ). Das bedeutet, dass:

• man kann sich nicht darauf verlassen, dass jedes gültige JSON-Schema vollständig von Swagger unterstützt wird.
• im Hinblick auf XML unterstützt Swagger nur die kanonische Darstellung einer Teilmenge der von JSON Schema Draft 4 bereitgestellten JSON-Strukturen.

Mit anderen Worten:

• Swagger (1.2 und 2.0) unterstützt nicht die Verwendung vieler JSON-Strukturen, die in Bezug auf 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. Mit Swagger müssen Sie mit Swagger beginnen und enden.

Das Erhalten eines JSON-Schemas ist theoretisch möglich, aber nicht einfach

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

• es war überhaupt nicht einfach
• habe enttäuscht festgestellt, dass ich nur einen Teil dessen verwenden kann, was JSON-Schema bietet. Wir hatten bereits einige JSON-Payloads vorgeschlagen und mussten damit beginnen, sie an das zulässige Swagger-Spezifikationsframework anzupassen.

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

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

Bei der Untersuchung anderer API-Spezifikations-Frameworks habe ich RAML gefunden. Da es durch die Unterstützung aller JSON Schema Draft 3/4- oder W3C XML Schema 1.0-Datenstrukturen von Grund auf erstellt wurde, war die Erfahrung hervorragend - da die Struktur meiner Nutzdaten entworfen wurde, war ich in der Lage, API-Spezifikationen sehr schnell zu erstellen und echte Anforderungen zu validieren und 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).

Das Korrigieren 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 sind, um REST API unter Verwendung der durch ein beliebiges JSON Schema Draft 4 oder W3C XML Schema 1.0 definierten Nutzdaten anzugeben.

Meine Antwort auf eine solche Frage wäre:

1. Entwerfen Sie Ihre Nutzdaten in JSON Schema Draft 4 oder W3C XML Schema
2. Beschreibe deine REST API mittels RAML (momentan v0.8).

Möglicherweise sind andere Spezifikationsframeworks verwendbar, aber Swagger (weder v1.2 noch v2.0) ist definitiv nicht der Fall. Abgesehen von der Bereitstellung wirklich vieler Funktionen (Codegenerierung, sehr gut aussehende Dokumentation der API und vieles mehr), kann die oben genannte aktualisierte Frage einfach nicht gelöst werden.

Es gibt ein python Tool, um dasselbe mit dem Namen openapi2jsonschema zu tun. Sie können es einfach mit pip installieren.

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.

Ich habe gerade ein Tool geschrieben pyswagger scheint Ihren Bedürfnissen zu entsprechen.

Es lädt die Swagger-API-Deklaration und kann Python-Objekt in/von Swagger-Grundelemente konvertieren. Stellen Sie auch eine Reihe von Client-Implementierungen bereit (einschließlich Requests & tornado.httpclient.AsyncHTTPClient), mit denen direkt Anfragen an den Swagger-fähigen Service gestellt 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 derzeit noch ziemlich neu. Willkommen für jeden Vorschlag.

Habe gerade Swagger entdeckt und mich gefragt, wie das eine Voraussetzung wäre.

Fand diese Antwort

Probieren Sie es direkt von hier aus:

http://petstore.swagger.wordnik.com/

und füge dies als deine URL ein:

http://petstore.swagger.wordnik.com/api/api-docs/pet

Ich sehe alle Modelle. Tust du nicht Oder vermisse ich etwas?

hier in ihrer Nutzergruppe: https://groups.google.com/forum/#!searchin/swagger-swaggersocket/schema/swagger-swaggersocket/bzxHxasWhQY/M35V1XWgm7EJ

die Frage ist, ob "die Modelle" sich auf ein gültiges JSON-Schema 4.0/JSON-Hyperschema beziehen

Ich hatte Erfolg damit:

swagger.yaml -> proto -> jsonschema

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