Dokumentiert eine umgebrochene REST-Antwort mit der swagger-UI
Ich habe ein WidgetDto, das ich mit swagger UI-Annotationen versehen habe. Die letzte Antwort umschließt eine Liste von WidgetDtos mit einer Metadatenschicht (pro Seite 21 von dies RESTful-Best-Practice-Dokument). Zum Beispiel:
%Vor%Mein Java-Code sieht so aus:
%Vor%Ich möchte dieses Muster für mehrere Ressourcen wiederverwenden, und ich möchte keine Listen-DTOs für jeden Antworttyp erstellen. Gibt es eine elegante Möglichkeit, diese Arten von Antwortkörpern mit swagger zu dokumentieren?
2 Antworten
Ihre Metadaten sind kein Teil Ihrer Ressource, aber sie sind Teil der Darstellung Ihrer Ressource.
In meinem Fall sind die Antworttypen " application / hal + json " und "/ Json ', jeder von ihnen verwendet einen anderen Wrapper mit verschiedenen Metadatas. Um dieses Problem zu lösen, habe ich ein externes Dokument erstellt, um diese zwei Wrapper und für jede von ihnen zu erklären, wie eine einzelne Ressource und eine Liste von Ressourcen mit Metadaten dargestellt werden.
Ich denke, dass meine Wahl richtig ist, weil ich die Ressource ihrer Darstellungen getrennt habe (pro Seite 7 'Manipulation von Ressourcen durch Repräsentationen' von dieses REST-konforme Best Practices-Dokument)
In Ihrem Fall geben Sie eine Liste von WidgetDtos zurück, die Metadatenebene ist ein Teil der Darstellung Ihrer Ressource.
Sie können jedoch eine generische Klasse wie Ressource und Ressourcen verwenden, die von spring-hateoas verwendet werden:
%Vor%Und benutze es so:
%Vor%Vor ein paar Monaten hatte ich ein ähnliches Problem, als ich ein Projekt für die Schule entwickelte. Die Lösung besteht darin, einen Umschlag zu erstellen und ihn immer zurückzugeben. Der Umschlag enthält ein Feld "Daten", das ein generisches ist; So können Sie es an jeden Datentyp binden. Beachten Sie, dass, obwohl ich es später benutze ich gelesen habe, dass es Scarecly verwendet werden sollte (ich denke, Ihr Fall ist ein gutes Beispiel für die Verwendung), aber technisch sollte ein Ausnahmeobjekt geworfen werden, wenn die Anfrage fehlgeschlagen ist.
Wie auch immer, dies ist meine Antwortklasse, die ich verwendet habe, um alle meine Antworten zurückzugeben:
%Vor%Nachdem dies eingestellt ist, werden wir die Antworten direkt vom Comtroller erstellen. Ich habe es ein bisschen geändert, damit es mit der Probe funktioniert, sollte genug lesbar sein. Beachten Sie, dass ich statische Methoden für meine Antworten habe: 'success ()', 'error ()' ...
%Vor% Und hier ist ein Beispiel des Antwortkörpers:
Hoffe, das hilft.
Tags und Links java rest jersey swagger swagger-ui