Ermöglicht Swagger 2.0 unreines REST-API-Design?

Question

Die aktuelle Swagger-Spezifikation behauptet, dass Swagger verwendet wird, um RESTful APIs zu beschreiben und zu dokumentieren. Ich denke, dies eher nicht der Fall ist, ich denke, Swagger für einfach beschreiben eine HTTP API für ein paar Gründe nützlich ist:

1. Die Swagger spec hat Elemente wie Path und Definition aber sie bilden nicht eindeutig auf die REST data elements wie Ressourcen-, Repräsentations- und Medientypen. Ich denke, um eine REST-API effektiv zu beschreiben, sollten Sie die expliziten REST-Datenelemente im Kontext Ihrer API definieren.
2. Hyperlinks sind keine erstklassigen Objekte in der Swagger-Spezifikation und daher können Hyperlinks und ihr kritisches beschreibendes Attribut, die Link-Beziehung, leicht weggelassen werden. Tatsächlich werden Hyperlinks überhaupt nicht erwähnt.
3. HTTP Pfade sind an der Front-und-Zentrum, das eine klare Verletzung eines Punktes Fieldings hat in seinem bekannten blog post zu sein scheint:

A REST API festen Ressourcennamen oder Hierarchien definieren darf nicht (eine offensichtliche Verbindung von Client und Server)

Im Grunde denke ich, APIs, um die Swagger 2.0-Spezifikation führt Sie definiert unter Verwendung eines API zu entwerfen, die nicht durch HATEOAS gezwungen wird, die REST verletzen würde.

Ist das korrekt oder fehle ich etwas?

Answer 1

stimme ich absolut zu. Swagger ist nicht gut geeignet, um wirklich REST-konforme APIs zu definieren. Das Problem ist, dass Leute REST auf viele verschiedene Arten definieren. Das Richardson Maturity Model hilft bei der Beschreibung dieser verschiedenen Definitionen.

Ebene 0 REST-APIs leiten alle Anforderungen über einen URI und eine HTTP-Methode weiter. Diese Ebene umfasst alle APIs, die HTTP verwenden, egal wie begrenzt. In der Praxis nennen die Leute diesen REST selten mehr, aber es geschieht (wahrscheinlich aus Marketinggründen).

Ebene 1 REST-APIs verwenden viele URIs, verwenden aber immer noch nur eine HTTP-Methode (normalerweise POST). In der Praxis wurde dies selten mehr REST genannt, aber es gab eine Zeit, in der es üblich war.

Level 2 In REST-APIs werden die Konzepte von Ressourcen und einheitlicher Schnittstelle eingeführt. Diese APIs verfügen über URIs, die Ressourcen darstellen und die HTTP-Methoden zum Ausführen von CRUD-Vorgängen für diese Ressourcen verwenden. In der Praxis fingen die Leute an, dies als RESTful zu bezeichnen, um es von Level 1 zu unterscheiden. Ich schätze Ruby on Rails für die Popularisierung dieser Interpretation von REST, aber ich kann das nicht unterstützen. In jedem Fall, , wenn Swagger behauptet, für die Beschreibung RESTful APIs zu sein, ist Level 2 die Definition, die sie auf beziehen.

Level 3 REST-APIs sind vollständig kompatibel mit dem REST-Architekturstil. Sie zeichnen sich insbesondere durch die Verwendung von HATEOAS aus. Alle Bedenken, die Sie in Ihrer Frage dargelegt haben, werden erst auf dieser Ebene berücksichtigt. In der Praxis haben einige Leute damit begonnen, diese Hypermedia-APIs aufzurufen, um sie von der jetzt festgeschriebenen Definition von RESTful zu unterscheiden, die sich auf die Level-2-Definition bezieht.

Ich würde sagen, dass Ihr Verständnis von REST "reifer" ist als das von Swagger und deshalb werden Sie nur frustriert versuchen, es zu benutzen (ich spreche aus Erfahrung). Meine persönliche Wahl für die Definition von Hypermedia APIs ist JSON Hyper-Schema. Es kann nicht alle großartigen Tools von Swagger enthalten, aber es erlaubt mir, APIs auf Stufe 3 zu schreiben. Das ist mehr, als ich für eine der gängigen API-Definitionssprachen sagen kann.