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
