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:
- Entwerfen Sie Ihre Nutzdaten in JSON Schema Draft 4 oder W3C XML Schema
- 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.
swagger->RAML->JSON Schema