Interested ? Let's do it now.
Prerequisites
- A GIT client
- JDK >= 1.8
- maven
Get the sample code
In a previous article, I built a REST API with Spring Boot to access a mongo database. You can start from this code.
See the article here :
Customize the code
Add the dependencies in your pom.xml
In order to work, you need some extra libraries. In the dependencies bloc, add the following sub-blocs :
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-data-rest</artifactId> <version>2.9.2</version> </dependency>
- swagger2 is necessary to generate the swagger file from your classes. It's a big JSON file, containing the documentation.
- swagger-ui allows you to generate the GUI of your documentation. Unlike the swagger file, it's human readable.
- data-rest is a complement to generate the documentation for a REST repository, which is our case here
Downgrade the Spring Boot version
Ooops. At this time, with springfox 2.9.2, you cannot use Spring boot 2 together with Springfox Data Rest. There is an issue in their github.
Modify in the version sub bloc of the parent bloc :
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>1.5.19.RELEASE</version> <relativePath/> <!-- lookup parent from repository --> </parent>
If you have a clue to make it work with Spring Boot 2, please leave a comment !
Add the swagger config class
Now, to make the Spring Boot magic happen, you need to add a class in src/main/java/com/example/demo
Call it SwaggerConfig.java with the folloging content :
import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } }
Enable swagger on the application class
Edit the DemoApplication.java in the following :package com.example.demo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.context.annotation.Import; import springfox.documentation.spring.data.rest.configuration.SpringDataRestConfiguration; import springfox.documentation.swagger2.annotations.EnableSwagger2; @SpringBootApplication @EnableSwagger2 @Import(SpringDataRestConfiguration.class) public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }
And you're done !
Build and run your application
As in the previous article build and run the app :$ mvn clean install
$ java -jar java -jar demo-0.0.1-SNAPSHOT.war
Browse your documentation
- To get the swagger file (JSON) :
http://localhost:8080/v2/api-docs
- To get the swagger-ui (HTML) :
http://localhost:8080/swagger-ui.html
- The full code can ge cloned from github :
git clone https://github.com/benoittouron/autodocumented-rest-api.git
