wake-up-neo.com

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

Ich habe eine ReSTFul API geschrieben in Simple Spring (kein Spring Boot, kein schickes Zeug!). Ich muss Swagger darin implementieren. Bisher hat mich JEDE Seite im Internet nur mit verwirrenden Konfigurationen und aufgeblähtem Code verrückt gemacht, den ich überhaupt nicht für tragbar befunden habe.

Hat jemand ein Beispielprojekt (oder eine Reihe detaillierter Schritte), das mir dabei helfen kann? Insbesondere suche ich nach einer guten Probe, die swagger-springmvc verwendet. Ich weiß, es hat "Beispiele", aber im besten Fall ist der esoterische Code entmutigend.

Ich muss klarstellen, dass ich nicht danach suche, "warum Swagger einfach der Beste ist". Ich benutze Spring Boot oder ähnliches nicht (und werde es für meine aktuelle Aufgabe nicht verwenden).

80
wavicle

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 und ermöglichen eine tiefere Anpassung, jedoch mit einigem Aufwand. 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 Bare-Minimum-Implementierung sieht mehr oder weniger gleich aus, verwendet jedoch jetzt die Klasse Docket anstelle der Klasse SwaggerSpringMvcPlugin:

@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 http://myapp/v2/api-docs Verfügbar.

Hinweis: Wenn Sie Spring Boot nicht verwenden, sollten Sie eine Jackson-Datenbindungsabhängigkeit hinzufügen. Da springfox jackson zur datenbindung verwendet.

Das Hinzufügen der Swagger-Benutzeroberfläche ist jetzt noch einfacher. Wenn Sie Maven verwenden, fügen Sie die folgende Abhängigkeit für das Webjar der Swagger-Benutzeroberfläche 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 die erforderlichen Dateien automatisch abrufen und die Benutzeroberfläche unter http://myapp/swagger-ui.html (Früher: http://myapp/springfox) Anzeigen. Wenn Sie Spring Boot nicht verwenden, müssen Sie, wie von yuriy-tumakha in der Antwort unten erwähnt, einen Ressourcen-Handler für die Dateien registrieren. 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 statische Dokumentationserstellung Funktion sieht auch ganz nett aus, obwohl ich es selbst nicht ausprobiert habe.

Swagger-SpringMVC (Swagger spec 1.2, älter)

Die Dokumentation für Swagger-SpringMVC kann ein bisschen verwirrend sein, ist jedoch unglaublich einfach einzurichten. Für die einfachste Konfiguration müssen Sie eine SpringSwaggerConfig - Bean erstellen und eine auf Anmerkungen basierende Konfiguration aktivieren (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 von SwaggerSpringMvcPlugin anstelle der vorherigen XML-definierten Bean vorzunehmen:

@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 http://myapp/api-docs Erstellt werden. Um die schicke 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 Datei index.html Auf der obersten Ebene des Swagger-UI-Verzeichnisses dist. Oben in der Datei wird JavaScript angezeigt, das auf die URL api-docs 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 nun zu http://myapp/path/to/swagger/index.html Navigieren, sollte die Swagger-Benutzeroberflächeninstanz für Ihr Projekt angezeigt werden.

117
woemler

Die Springfox Swagger-Benutzeroberfläche funktioniert für mich, nachdem WebJar-Abhängigkeiten und Ressourcenzuordnungen hinzugefügt wurden. 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 Spring Annotation 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 {
 }
12
Yuriy Tumakha

Sie können auch das swagger-maven-plugin verwenden, um swagger.json zu generieren und auf Ihre statische swagger-ui zu kopieren.

Bitte überprüfen Sie ein einfaches Beispiel eines funktionierenden Plugins mit Spring MVC-Anmerkungen auf diesem Repo:

https://github.com/khipis/swagger-maven-example

oder für JAX-RS

https://github.com/kongchen/swagger-maven-example

1
kkhipis