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

J’ai une API ReSTFul écrite en simple Spring (pas de Spring Boot, pas de trucs de fantaisie!). Je dois implémenter Swagger dans ceci. Jusqu’ici, CHAQUE page sur Internet m’a seulement rendu fou avec des configurations confuses et du code gonflé que je ne trouvais pas du tout portable.

Est-ce que quelqu’un a un exemple de projet (ou une série d’étapes détaillées) qui peut m’aider à accomplir cela? En particulier, je recherche un bon échantillon utilisant swaggerspringmvc. 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 pour ma tâche actuelle ne pas utiliser) Spring Boot ou autre.

Springfox (Swagger spec 2.0, actuel)

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

Dépendance de Maven

 io.springfox springfox-swagger2 2.5.0  

L’implémentation minimale ne ressemble plus à la même chose, mais utilise désormais 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’ http://myapp/v2/api-docs .

Remarque: Si vous n’utilisez pas l’amorçage Spring, vous devez append une dépendance jackson-databind. Depuis que 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 l’interface Web Swagger:

  io.springfox springfox-swagger-ui 2.5.0  

Si vous utilisez Spring Boot, votre application Web doit automatiquement récupérer les fichiers nécessaires et afficher l’interface utilisateur à l’ http://myapp/swagger-ui.html (anciennement: http://myapp/springfox ). Si vous n’utilisez pas Spring Boot, comme le mentionne Yuriy-tumakha dans la réponse ci-dessous, vous devrez enregistrer un gestionnaire de ressources pour les fichiers. La configuration Java ressemble à ceci:

 @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é de génération de documentation statique semble également très intéressante, même si je ne l’ai 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 incroyablement facile à configurer. La configuration la plus simple nécessite la création d’un bean SpringSwaggerConfig et l’activation de la configuration basée sur des annotations (ce que vous avez probablement déjà fait dans votre projet Spring MVC):

   

Cependant, je pense que cela vaut la peine de prendre une étape supplémentaire en définissant une configuration Swagger personnalisée à l’aide de SwaggerSpringMvcPlugin , au lieu du bean XML défini précédemment:

 @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, vous devriez maintenant voir vos spécifications API créées à l’ http://myapp/api-docs . Pour configurer l’interface utilisateur de Swagger, vous devez cloner les fichiers statiques du projet GitHub et les placer dans votre projet. Assurez-vous que votre projet est configuré pour servir les fichiers HTML statiques:

  

Ensuite, éditez le fichier index.html au niveau supérieur du répertoire dist interface utilisateur Swagger. En haut du fichier, vous verrez du code JavaScript qui fait référence à l’ api-docs d’un autre projet. Modifiez ceci pour pointer 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 devez voir l’instance de l’interface utilisateur Swagger pour votre projet.

L’interface utilisateur de Springfox Swagger fonctionne pour moi après l’ajout de dépendances WebJar et de mappages de ressources. http://www.webjars.org/documentation#springmvc

   io.springfox springfox-swagger2 2.2.2   io.springfox springfox-swagger-ui 2.2.2   org.webjars bootstrap 3.3.5  

spring-servlet.xml:

   

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 { } 

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

S’il vous plaît vérifier un échantillon simple de plug-in de travail avec annotations Spring MVC sur ce repo:

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

ou pour JAX-RS

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