Spring api docs using swagger

Just want to write a quick post on need for API specifications for your REST services. This is especially important if you are adopting microservices .

How to provide documentation for your api's ?  What information is required and how to provide this information that can be easily understood and used by other teams?   .

This concept is same as WSDL when using a SOAP service , the interesting thing is when ever we want to consume a soap service immediately WSDL comes to mind . But so far I haven't seen this adoption to REST based service . Industry is moving towards a  micro-service model and light weight api's  become ubiquitous this becomes a compelling need.

Swagger comes to the rescue in providing specifications for  defining the interface to the rest service.
https://en.wikipedia.org/wiki/OpenAPI_Specification. Most important thing is when you use a framework like spring you  don't have to understand swagger to the extent of writing them manually . Spring can do that for you .

Here is how you do it

Include swagger library in pom.xml ( version I use in 2.7.0 , you can use the latest )

<dependency> 

 <groupId>io.springfox</groupId> 

 <artifactId>springfox-swagger2</artifactId > 

<version>2.7.0</version> 

</dependency>

Enable swagger Configuration . I am using Swagger 2 , use the version that is accepted with in your organization 

@Configuration

@EnableSwagger2

public class SwaggerConfig {                                    

    @Bean

    public Docket api() { 

        return new Docket(DocumentationType.SWAGGER_2)  

          .select()                                  

          .apis(RequestHandlerSelectors.any())              

          .paths(PathSelectors.any())                          

          .build();                                           

    }

}

Now when you start your spring boot application
the api docs are available , it provides all the information for your consumers

http://localhost:8080/v2/api-docs



All these data along with the model objects are now part of my specification . I can share this information with other teams that want to consume my service .

As your application grows and model changes the documentation is automatically reflected with the latest information .

Here is an complete example in github
https://github.com/arun2dot0/simple-rest-service-swagger