Ich habe eine ReSTFul-API in einfachem Spring geschrieben (kein Spring Boot, kein schickes Zeug!). Ich muss Swagger in dieses implementieren. Bisher hat mich JEDE Seite im Internet nur durch verwirrende Konfigurationen und aufgeblähten Code verrückt gemacht, den ich überhaupt nicht tragbar fand.
Hat jemand ein Beispielprojekt (oder eine Reihe detaillierter Schritte), das mir dabei helfen kann? Insbesondere suche ich eine gute Probe, die swagger-springmvc verwendet. Ich weiß, dass es "Samples" gibt, aber im besten Fall ist der esoterische Code entmutigend.
Ich muss klarstellen, dass ich nicht nach "warum Swagger einfach der Beste ist" suche. Ich verwende Spring Boot oder ähnliches nicht (und für meine aktuelle Aufgabe auch nicht).
spring
spring-mvc
swagger
Wavicle
quelle
quelle
Antworten:
Springfox (Swagger spec 2.0, aktuell)
Springfox hat Swagger-SpringMVC ersetzt und unterstützt jetzt beide Swagger-Spezifikationen 1.2 und 2.0. Die Implementierungsklassen haben sich geändert, was eine tiefere Anpassung ermöglicht, jedoch mit etwas Arbeit. Die Dokumentation wurde verbessert, es müssen jedoch noch einige Details für die erweiterte Konfiguration hinzugefügt werden. Die alte Antwort für die 1.2-Implementierung finden Sie weiter unten.
Maven-Abhängigkeit
Die Implementierung mit dem Minimum sieht mehr oder weniger gleich aus, verwendet jetzt jedoch die
Docket
Klasse anstelle derSwaggerSpringMvcPlugin
Klasse:Ihre Swagger 2.0 API-Dokumentation ist jetzt unter verfügbar
http://myapp/v2/api-docs
.Das Hinzufügen der Unterstützung für die Swagger-Benutzeroberfläche ist jetzt noch einfacher. Wenn Sie Maven verwenden, fügen Sie die folgende Abhängigkeit für das Swagger UI-Webjar hinzu:
Wenn Sie Spring Boot verwenden, sollte Ihre Web-App automatisch die erforderlichen Dateien abrufen und die Benutzeroberfläche unter
http://myapp/swagger-ui.html
(früher :) anzeigenhttp://myapp/springfox
. Wenn Sie Spring Boot nicht verwenden, müssen Sie, wie in der folgenden Antwort erwähnt, einen Ressourcenhandler für die Dateien registrieren, wie yuriy-tumakha erwähnt. Die Java-Konfiguration sieht folgendermaßen aus:Die neue Funktion zur Generierung statischer Dokumentationen sieht auch ganz gut aus, obwohl ich sie selbst nicht ausprobiert habe.
Swagger-SpringMVC (Swagger-Spezifikation 1.2, älter)
Die Dokumentation für Swagger-SpringMVC kann etwas verwirrend sein, ist aber unglaublich einfach einzurichten. Die einfachste Konfiguration erfordert das Erstellen einer
SpringSwaggerConfig
Bean und das Aktivieren der annotationsbasierten Konfiguration (was Sie wahrscheinlich bereits in Ihrem Spring MVC-Projekt tun):Ich denke jedoch, dass es sich lohnt, den zusätzlichen Schritt des Definierens einer benutzerdefinierten Swagger-Konfiguration mithilfe der
SwaggerSpringMvcPlugin
anstelle der vorherigen XML-definierten Bean zu unternehmen :Wenn Sie Ihre Anwendung ausführen, sollte jetzt Ihre API-Spezifikation unter erstellt werden
http://myapp/api-docs
. Um die ausgefallene Swagger-Benutzeroberfläche einzurichten, müssen Sie die statischen Dateien aus dem GitHub-Projekt klonen und in Ihr Projekt einfügen. Stellen Sie sicher, dass Ihr Projekt für die Bereitstellung der statischen HTML-Dateien konfiguriert ist:Bearbeiten Sie dann die
index.html
Datei auf der obersten Ebene des Swagger-UI-dist
Verzeichnisses. Oben in der Datei sehen Sie JavaScript, das auf dieapi-docs
URL eines anderen Projekts verweist . Bearbeiten Sie dies, um auf die Swagger-Dokumentation Ihres Projekts zu verweisen:Wenn Sie jetzt zu navigieren
http://myapp/path/to/swagger/index.html
, sollte die Swagger-UI-Instanz für Ihr Projekt angezeigt werden.quelle
PathSelectors.
, um Menschen zu helfen, die mit statischem Import vonregex
2.5.0
während ich dies schreibe)Die Springfox Swagger-Benutzeroberfläche funktioniert für mich nach dem Hinzufügen von WebJar-Abhängigkeiten und Ressourcenzuordnungen. http://www.webjars.org/documentation#springmvc
spring-servlet.xml:
oder Frühlingsanmerkung https://github.com/springfox/springfox-demos/blob/master/spring-java-swagger/src/main/java/springfoxdemo/java/swagger/SpringConfig.java
Swagger2 sollte aktiviert sein
quelle
/swagger-resources
beim Öffnen immer noch einen 404 answagger-ui.html
. Irgendwelche Tipps? Vielleicht mehr Ressourcenzuordnungen?Sie können auch das swagger-maven-plugin verwenden, um swagger.json zu generieren und es in Ihre statische swagger-ui zu kopieren.
Bitte überprüfen Sie ein einfaches Beispiel eines funktionierenden Plugins mit Spring MVC-Anmerkungen zu diesem Repo:
https://github.com/khipis/swagger-maven-example
oder für JAX-RS
https://github.com/kongchen/swagger-maven-example
quelle