Swagger 2 dependency in Spring Boot

Hi folks, hope i found you well in these tough time. In this particular blog i am going to implement Swagger 2 into a spring boot web application.

Table of content
What is swagger?
Implementing  a spring boot API using swagger.


Swagger has a vast set of tools for APIs development.

Swagger is a tool to achieve the following

Develop APIs
Interact with APIs
Document APIs

The third one i.e. documenting APIs given swagger a lots of popularity. It is an excellent tool to document APIs. The most popular tool to do the same using something called swagger UI.
In this blog we are focusing on the third one. We are going to implement a spring boot APIs and it's documentation using swagger UI.

But there are some of the questions that should be answered before diving in deeper.

Why we need a tools to documenting an API?
The answer to above question is pretty much simpler, when some one build an API and some other user is going to consume that particular API, then consumer need to know all the end points, payload required to access those end points, what is the response code, error code they get from APIs and all. One way is to simply ask the API developer about all the mentioned question and the other way is to create an document mentioning all these stuff and handed over to the consumer, that will provide all the answers to the consumers pretty simple right! But why we need a tools for that we can do it manually these things while creating the  API, of course it will take some more effort of API developer rather than the actual development of API. But think of a situation when developer came up with some ideas or changes in API like response structure, or they may be increases the end points (in short any kind of updation in existing API). Now there is a need o f updation of documentation as well. In agile development updation is a continious process (you can deny about it), so updating each and every time the API document will become more frustrating. Swagger plays a vital role at that point. You just need to pay attention at you APIs changes and rest of the things related to documentation will be taken care about swagger UI tool.

In traditional API development methodology we have corresponding documentation tool as well for example SOAP has WSDL for documentation, unfortunatily REST has no any documentation tool.


Swagger allows you to create auto generated documentation for your APIs based on metadata you provided. It will keep your documentation in a sync with your API.

Swagger dependency can be linked in any languages to develop APIs in that particular language. 

Here i am going to spring implementation of swagger using Swagger 2 spring dependency.

Adding Swagger to Spring Boot involves these simple steps

Get a basic spring boot application skeleton from spring initializer 
Getting the Swagger 2 spring dependency
Enable Swagger in your code
Configuring Swagger (optional )
Adding details as annotation to APIs (optional )

Get a empty spring boot application skeleton from spring initializer with web dependency, and import it into eclipse or STS or Intellij IDEA.



Next, add swagger 2 dependency into pom.xml.

































 
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->  
 <dependency>  
   <groupId>io.springfox</groupId>  
   <artifactId>springfox-swagger2</artifactId>  
   <version>2.9.2</version>  
 </dependency>  



Here, we are going to create very basic api to store and retrieve addressbook data with three end points.

addContact : adding new contact by passing allowed payload.
getAllContact : getting all contacts from memory.
getContact : get the desired contact by passing id of contact.



So, first thing first, create modal for contacts and controller to handle these api call.

I kept three attributes id, name and phone into my Contact Modal.
Contact.java
 package com.tech.reloded.techReloded;  
 /**  
  * The Class Contact.  
  */  
 public class Contact {  
      /** The id. */  
      private String id;  
      /** The name. */  
      private String name;  
      /** The phone. */  
      private String phone;  
      /**  
       * Gets the id.  
       *  
       * @return the id  
       */  
      public String getId() {  
           return id;  
      }  
      /**  
       * Sets the id.  
       *  
       * @param id the new id  
       */  
      public void setId(String id) {  
           this.id = id;  
      }  
      /**  
       * Gets the name.  
       *  
       * @return the name  
       */  
      public String getName() {  
           return name;  
      }  
      /**  
       * Sets the name.  
       *  
       * @param name the new name  
       */  
      public void setName(String name) {  
           this.name = name;  
      }  
      /**  
       * Gets the phone.  
       *  
       * @return the phone  
       */  
      public String getPhone() {  
           return phone;  
      }  
      /**  
       * Sets the phone.  
       *  
       * @param phone the new phone  
       */  
      public void setPhone(String phone) {  
           this.phone = phone;  
      }  
 }  


 
AddressBookController.java 
 
 package com.tech.reloded.techReloded;  
 import java.util.ArrayList;  
 import java.util.List;  
 import java.util.concurrent.ConcurrentHashMap;  
 import org.springframework.web.bind.annotation.GetMapping;  
 import org.springframework.web.bind.annotation.PathVariable;  
 import org.springframework.web.bind.annotation.PostMapping;  
 import org.springframework.web.bind.annotation.RequestBody;  
 import org.springframework.web.bind.annotation.RequestMapping;  
 import org.springframework.web.bind.annotation.RestController;  
 /**  
  * The Class AddressBookResource.  
  */  
 @RestController  
 @RequestMapping("/api")  
 public class AddressBookController {  
      /** The contacts. */  
      ConcurrentHashMap<String, Contact> contacts = new ConcurrentHashMap<>();  
      /**  
       * Gets the contact.  
       *  
       * @param id the id  
       * @return the contact  
       */  
      @GetMapping("/{id}")  
      public Contact getContact(@PathVariable String id) {  
           return contacts.get(id);  
      }  
      /**  
       * Gets the all contact.  
       *  
       * @return the all contact  
       */  
      @GetMapping("/")  
      public List<Contact> getAllContact(){  
           return new ArrayList<Contact>(contacts.values());  
      }  
      /**  
       * Adds the contact.  
       *  
       * @param contact the contact  
       * @return the contact  
       */  
      @PostMapping("/")  
      public Contact addContact(@RequestBody Contact contact) {  
           contacts.put(contact.getId(), contact);  
           return contact;  
      }  
 }