Eine "einfache" Möglichkeit, Swagger in einer Spring MVC-Anwendung zu implementieren

85

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).

Wavicle
quelle
4
Bei den Beispielen gehe ich davon aus, dass Sie sich auf github.com/adrianbk/swagger-springmvc-demo beziehen . Ich würde Sie tatsächlich ermutigen, ein Ticket direkt auf swagger-springmvc zu öffnen, da es für sie wichtig ist zu wissen, dass einige ihrer potenziellen Benutzer der Meinung sind, dass die Dokumente unzureichend sind, damit sie es verbessern können.
Ron

Antworten:

122

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

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency> 

Die Implementierung mit dem Minimum sieht mehr oder weniger gleich aus, verwendet jetzt jedoch die DocketKlasse anstelle der SwaggerSpringMvcPluginKlasse:

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.regex("/api/.*"))
            .build()
            .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("TITLE")
            .description("DESCRIPTION")
            .version("VERSION")
            .termsOfServiceUrl("http://terms-of-services.url")
            .license("LICENSE")
            .licenseUrl("http://url-to-license.com")
            .build();
    }

}

Ihre Swagger 2.0 API-Dokumentation ist jetzt unter verfügbar http://myapp/v2/api-docs.

Hinweis: Wenn Sie Spring Boot nicht verwenden, sollten Sie die Jackson-Databind-Abhängigkeit hinzufügen. Da Springfox Jackson für die Datenbindung verwendet.

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:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>

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 :) anzeigen http://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:

@Configuration
@EnableWebMvc
public class WebAppConfig extends WebMvcConfigurerAdapter {

    @Override 
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

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 SpringSwaggerConfigBean und das Aktivieren der annotationsbasierten Konfiguration (was Sie wahrscheinlich bereits in Ihrem Spring MVC-Projekt tun):

<mvc:annotation-driven/>
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

Ich denke jedoch, dass es sich lohnt, den zusätzlichen Schritt des Definierens einer benutzerdefinierten Swagger-Konfiguration mithilfe der SwaggerSpringMvcPluginanstelle der vorherigen XML-definierten Bean zu unternehmen :

@Configuration
@EnableSwagger
@EnableWebMvc
public class SwaggerConfig {

    private SpringSwaggerConfig springSwaggerConfig;

    @SuppressWarnings("SpringJavaAutowiringInspection")
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }

    @Bean
    public SwaggerSpringMvcPlugin customImplementation(){

        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo())
                .includePatterns(".*api.*"); // assuming the API lives at something like http://myapp/api
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("TITLE")
            .description("DESCRIPTION")
            .version("VERSION")
            .termsOfServiceUrl("http://terms-of-services.url")
            .license("LICENSE")
            .licenseUrl("http://url-to-license.com")
            .build();
    }

}

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:

<mvc:resources mapping="*.html" location="/" />

Bearbeiten Sie dann die index.htmlDatei auf der obersten Ebene des Swagger-UI- distVerzeichnisses. Oben in der Datei sehen Sie JavaScript, das auf die api-docsURL eines anderen Projekts verweist . Bearbeiten Sie dies, um auf die Swagger-Dokumentation Ihres Projekts zu verweisen:

  if (url && url.length > 1) {
    url = url[1];
  } else {
    url = "http://myapp/api-docs";
  }

Wenn Sie jetzt zu navigieren http://myapp/path/to/swagger/index.html, sollte die Swagger-UI-Instanz für Ihr Projekt angezeigt werden.

Woemler
quelle
1
@MikhailBatcer: Ich habe die Antwort mit der Maven-Abhängigkeit für Springfox aktualisiert. Dies ist die einzige Abhängigkeit, die Sie in Ihr Projekt aufnehmen müssen, es sei denn, Sie möchten auch die Swagger-Benutzeroberfläche oder statische Dokumente.
Woemler
2
sieht aus wie die UI-URL jetzt /myapp/swagger-ui.html und nicht / springfox
chrismarx
7
Der Vollständigkeit halber: Die 'regex'-Methode im Beispiel' SwaggerConfig 'von springfox stammt aus' springfox.documentation.builders.PathSelectors.regex (String) '. Wenn ich eine ganze Weile
gebraucht habe
2
Ich habe mir die Freiheit genommen, hinzuzufügen PathSelectors., um Menschen zu helfen, die mit statischem Import vonregex
Tim Büthe
1
Bemerkenswert: Wenn Sie diese Anweisungen genau befolgen und SpringBoot nicht verwenden, wird aufgrund der verschiedenen Versionen der von Maven abgerufenen Bibliotheken springfox und springfox-ui ein Laufzeitfehler angezeigt. Beginnen Sie stattdessen mit der neuesten Version von beiden, wenn möglich ( 2.5.0während ich dies schreibe)
Kip
13

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

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.2.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.2.2</version>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>3.3.5</version>
    </dependency>

spring-servlet.xml:

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

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

 @EnableSwagger2
 public class SwaggerConfiguration {
 }
Yuriy Tumakha
quelle
Das hat mir sehr geholfen, aber ich bekomme /swagger-resourcesbeim Öffnen immer noch einen 404 an swagger-ui.html. Irgendwelche Tipps? Vielleicht mehr Ressourcenzuordnungen?
Tim Büthe
Es sieht so aus, als ob Swagger-Ressourcen nicht im Root-Kontext stehen. Dies kann behoben werden, indem DispatcherServlet dem Stammkontext zugeordnet wird. Schauen Sie sich das Problem 983 und F an. Wie konfiguriert man swagger-ui für Nicht-Springboot-Anwendungen?
Yuriy Tumakha