web-dev-qa-db-de.com

Was ist der Vorteil von Spring? REST Dokumente, die mit Swagger verglichen werden

Spring REST Docs wurde kürzlich veröffentlicht und in der Dokumentation heißt es:

Dieser Ansatz befreit Sie von den Einschränkungen, die Tools wie Swagger auferlegen

Ich wollte also fragen, wann Spring REST Docs im Vergleich zu Swagger vorzuziehen ist und welche Einschränkungen es gibt.

22
evgeniy44

Ich habe hier gerade eine Präsentation gesehen, die unter anderem Ihre Frage berührt:

https://www.youtube.com/watch?v=k5ncCJBarRI&t=26m58s

  • Swagger unterstützt Hypermedia überhaupt nicht/es ist URI-zentrisch

  • Swaggers Methode, Ihren Code zu prüfen, kann hinter Ihrem Code zurückbleiben. Es ist möglich, dass Sie Änderungen am Code vornehmen, die Swagger nicht versteht und nicht ordnungsgemäß verarbeitet wird, bevor Swagger aktualisiert wird.

  • Swagger erfordert viele Anmerkungen, und es ist schmerzhaft, den gewünschten beschreibenden Text in ein API-Dokument in Anmerkungen aufzunehmen.

  • Es gibt nur einige Dinge, die Swagger bei der Überprüfung Ihres Codes nicht herausfinden kann.

In jedem Fall sind dies nur ein paar Punkte. Der Moderator macht es viel besser, darüber zu diskutieren, als ich könnte.

22
Edgar Ngwenya

Ich dachte, ich würde mitspielen, um Swagger ein wenig mehr Kontext zu geben, was es ist und was es nicht ist. Ich glaube, das könnte helfen, Ihre Frage zu beantworten.

Swagger 2.0 wird von vielen großen Namen und großen Plattformen wie Microsoft Azure, Paypal, SwaggerHub.com, DynamicApis.com usw. angenommen. Etwas zu bedenken ist, dass Swagger sehr einfach eine Spezifikation ist . Es ist kein Rahmen. Es gibt eine Menge von frameworks out, um Swagger-Ausgaben zu generieren, die Ihren Code durchsuchen und Ihre API-Informationen durchsuchen, um die Swagger 2.0-JSON-Datei zu erstellen, die Ihre API darstellt. Die Swagger-Benutzeroberfläche, auf der Sie Ihre APIs sehen, wird direkt von dieser Swagger 2.0-JSON-Datei gesteuert. fiddler es auszuprobieren

Es ist wichtig anzumerken, dass ein Framework, das erstellt wurde, um Ihnen die Verwendung von "swagger" zu ermöglichen, nicht so ist, wie Swagger funktionieren muss (d. H. Es ist vollständig die Implementierung des 3rd Party Frameworks). Wenn das Framework, das Sie zum Generieren Ihrer Swagger 2.0-Dokumente verwenden, und die Benutzeroberfläche nicht für Sie funktioniert, sollten Sie in der Lage sein, ein anderes Framework zu finden, das die Swagger-Artefakte generiert und die Technologien austauscht.

Hoffe das hilft.

9
Jerrod Horton

Es gibt einige Einschränkungen beim Swagger und dem spezifischen Federstapel.

Beispiel: Mit "param" in Ihrem Request-Mapping können Sie mehrere Methoden mit derselben URL definieren. Vereinfachen Sie also Ihren Code . Swagger zeigt jedoch nur eine Methode

5
Sbert

Von Spring REST docs :

Das Ziel von Spring REST Docs ist es, Ihnen zu helfen, Dokumentation für Ihre RESTful-Services zu erstellen, die genau und lesbar ist

Dieser testgetriebene Ansatz gewährleistet die Genauigkeit der Dokumentation Ihres Dienstes. Wenn ein Snippet nicht korrekt ist, schlägt der Test fehl, der es erzeugt.

Spring REST dokumentiert die Vorteile:

  • Die Dokumentation ist im Testcode geschrieben, sodass der Hauptcode nicht mit vielen Anmerkungen und Beschreibungen überladen wird
  • Die generierten Dokumente und Beispiele sind genau, da der entsprechende Test bestanden werden muss
  • Dokumente können spezifischere und beschreibende Snippets bereitstellen
  • Format ist für die Veröffentlichung geeignet

Spring REST weist Nachteile auf:

  • Benötigt mehr Arbeit
  • Die Dokumentation enthält Anforderungs-/Antwortbeispiele, jedoch keine interaktiven Tools zum Ändern und Ausprobieren von Anforderungen 

Swagger-Vorteile:

  • Schnelle, automatisierte Generierung aus einem Code
  • Interaktive Anforderungsausführung - kann zur Abnahmeprüfung verwendet werden 
  • Um die OpenAPI Spezifikation herum gebaut 

Swagger-Nachteile:

  • Für eine anschaulichere Dokumentation sind viele Anmerkungen erforderlich
  • Tests beziehen sich nicht auf die Dokumentation, daher kann die Dokumentation manchmal von der Realität abweichen
0
Justas

Ein Nachteil von Swagger ist, dass es keine Modelle mit zyklischen Abhängigkeiten verarbeiten kann. Wenn ein Modell eine zyklische Abhängigkeit aufweist und Swagger aktiviert ist, stürzt der Spring-Boot-Server ab.

0
user1702260