web-dev-qa-db-fra.com

Un moyen 'simple' d'implémenter Swagger dans une application Spring MVC

J'ai une API ReSTFul écrite en Spring simple (pas de Spring Boot, pas de trucs fantaisistes!). Je dois implémenter Swagger dans ce domaine. Jusqu'ici, CHAQUE page sur Internet ne m'a rendu fou qu'avec des configurations confuses et un code gonflé que je n'ai pas trouvé portable du tout.

Quelqu'un a-t-il un exemple de projet (ou un ensemble d'étapes détaillées) qui peut m'aider à accomplir cela? En particulier, je recherche un bon échantillon utilisant swagger-springmvc. Je sais qu'il a des 'échantillons', mais au mieux, le code ésotérique est décourageant.

Je dois préciser que je ne cherche pas "pourquoi Swagger est tout simplement le meilleur". Je n'utilise pas (et ma tâche actuelle ne sera pas utilisée) Spring Boot ou autre.

springspring-mvcswagger
80
wavicle

Springfox (spéc. Swagger 2.0, actuel)

Springfox a remplacé Swagger-SpringMVC et prend désormais en charge les spécifications 1.2 et 2.0 de Swagger. Les classes d'implémentation ont changé, permettant une personnalisation plus poussée, mais avec un peu de travail. La documentation a été améliorée, mais certains détails doivent encore être ajoutés pour la configuration avancée. L'ancienne réponse pour l'implémentation 1.2 est toujours disponible ci-dessous.

Dépendance Maven 

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

L'implémentation à strict minimum a plus ou moins la même apparence, mais utilise maintenant la classe Docket au lieu de la classe 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();
    }

}

Votre documentation sur l'API Swagger 2.0 sera désormais disponible à l'adresse http://myapp/v2/api-docs.

Remarque: Si vous n'utilisez pas le démarrage Spring, vous devez ajouter une dépendance jackson-databind. Depuis springfox utilise jackson pour la liaison de données.

L'ajout du support Swagger UI est encore plus facile maintenant. Si vous utilisez Maven, ajoutez la dépendance suivante pour le webjar de l'interface utilisateur Swagger:

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

Si vous utilisez Spring Boot, votre application Web doit alors sélectionner automatiquement les fichiers nécessaires et afficher l'interface utilisateur sous http://myapp/swagger-ui.html (anciennement: http://myapp/springfox). Si vous n'utilisez pas Spring Boot, alors, comme le mentionne yuriy-tumakha dans la réponse ci-dessous, vous devrez enregistrer un gestionnaire de ressources pour les fichiers. La configuration de Java se présente comme suit:

@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/");
    }

}

La nouvelle fonctionnalité génération de documentation statique est également très jolie, bien que je ne l’aie pas essayée moi-même.

Swagger-SpringMVC (Swagger spec 1.2, plus ancien)

La documentation de Swagger-SpringMVC peut être un peu déroutante, mais elle est en fait incroyablement facile à configurer. La configuration la plus simple nécessite la création d'un bean SpringSwaggerConfig et l'activation d'une configuration basée sur des annotations (ce que vous avez probablement déjà fait dans votre projet Spring MVC):

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

Cependant, je pense que cela vaut la peine de prendre l'étape supplémentaire consistant à définir une configuration Swagger personnalisée à l'aide de SwaggerSpringMvcPlugin, au lieu du bean précédent défini par XML:

@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();
    }

}

Lorsque vous exécutez votre application, votre spécification d'API devrait maintenant être créée à l'emplacement http://myapp/api-docs. Pour obtenir la configuration sophistiquée de l’interface utilisateur Swagger, vous devez cloner les fichiers statiques de projet GitHub et les insérer dans votre projet. Assurez-vous que votre projet est configuré pour servir les fichiers HTML statiques:

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

Editez ensuite le fichier index.html au niveau supérieur du répertoire Swagger UI dist. En haut du fichier, vous verrez du code JavaScript faisant référence à l'URL api-docs d'un autre projet. Modifiez cela pour qu'il pointe vers la documentation Swagger de votre projet:

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

Maintenant, lorsque vous accédez à http://myapp/path/to/swagger/index.html, vous devriez voir l'instance d'interface utilisateur Swagger pour votre projet.

117
woemler

L’interface utilisateur Springfox Swagger fonctionne pour moi après l’ajout de mappages de dépendances et de ressources WebJar. 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/"/>

ou Spring Annotation https://github.com/springfox/springfox-demos/blob/master/spring-Java-swagger/src/main/Java/springfoxdemo/Java/swagger/SpringConfig.Java

Swagger2 devrait être activé

 @EnableSwagger2
 public class SwaggerConfiguration {
 }
12
Yuriy Tumakha

Vous pouvez également envisager d'utiliser swagger-maven-plugin pour générer swagger.json et le copier sur votre swagger-ui statique.

Veuillez vérifier un exemple simple de plug-in de travail avec les annotations Spring MVC sur ce référentiel:

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

ou pour JAX-RS

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

1
kkhipis