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

Spring Mongo Integration

Setting up and using MongoDB in the Spring application is a simple two step process.Specify the Mongo template in the application configuration , then customize the ApplicationConfig . Step 1 Include the Mongo configuration in the application context

<mongo:db-factory id="mongoDbFactory" dbname="my-store" />
 
 <mongo:mapping-converter id="mongoConverter" base-package="springdata.mongodb">
  <mongo:custom-converters base-package="springdata.mongodb" />
 </mongo:mapping-converter>
 
 <bean id="mongoTemplate" class="org.springframework.data.mongodb.core.MongoTemplate">
  <constructor-arg ref="mongoDbFactory" />
  <constructor-arg ref="mongoConverter" />
  <property name="writeConcern" value="SAFE" />
 </bean>
 
 <mongo:repositories base-package="springdata.mongodb" />

Step2 Setup the ApplicationConfig in the base-package

@ComponentScan
@EnableMongoRepositories
class ApplicationConfig extends AbstractMongoConfiguration {

 
 @Override
 protected String getDatabaseName() {
 return "my-store";
 
 }

 
 @Override
 public Mongo mongo() throws Exception {

  Mongo mongo = new Mongo();
  mongo.setWriteConcern(WriteConcern.SAFE);

  return mongo;
 }

}

After the two steps the Mongo can be included in the application by simply autowiring

@Autowired Mongo mongo;