Document REST API Using Swagger 2 and Spring MVC

In this post, we'll learn how to document REST api's using Swagger 2 and Spring MVC.

Check out the below video for the same.



Summary of the video:

1. Add Swagger 2 and jackson-databind dependency in pom.xml

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.2.2</version>
  </dependency>
 
  <dependency>
   <groupId>com.fasterxml.jackson.core</groupId>
   <artifactId>jackson-databind</artifactId>
   <version>2.5.0</version>
  </dependency>

2. Configure servlet.xml to include the swagger config bean

<bean class="springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration" id="swagger2Config">  
</bean>

3. Annotate controller classes as per your requirement

@Api(value="Hello World", description="Hello World Controller")

4. add swagger ui dependency
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.2.2</version>
  </dependency> 

5. map swagger resources in servlet.xml

<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"></mvc:resources>
  <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"></mvc:resources>


Comment below in case you guys face any issue. I'll see if I can help you out.
See you around.
Share on Google+

About Sujit Horakeri

Sujit Horakeri is a game freak just like any other next door guy you would come across. He is a Web Developer by Profession, Game Developer by Choice.
Connect with him on:
    Blogger
    Facebook

7 comments:

  1. HI Sujit, this was a great tutorial, however I am not able to bring up swagger ui, can you please help, I have posted the question here:
    http://stackoverflow.com/questions/37055447/swagger-ui-not-working-rest-api

    Thanks!

    ReplyDelete
  2. Hi,

    I'm getting blank screen in the swagger. i have few put and get methods they are not showing up and the dropdown at the right is having blank value. if possible help me in getting this issue resolved. thanks

    ReplyDelete
  3. Followed the exact steps to get the configuration setup done for existing project. Only difference is using Spring3.x veresion (3.2.3.RELEASE).

    Now For me the swagger ui is showing up but for some reason when I try to get the api-docs.json file, by putting endpoint in the browser :

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

    I get This resource does not exist.
    404


    ReplyDelete
  4. Followed the exact steps to get the configuration setup done for existing project. Only difference is using Spring3.x veresion (3.2.3.RELEASE).

    Now For me the swagger ui is showing up but for some reason when I try to get the api-docs.json file, by putting endpoint in the browser :

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

    I get This resource does not exist.
    404


    ReplyDelete
  5. Please share code. Thank so much.

    ReplyDelete
  6. I am getting bank swagger ui and 404 at /v2/api-docs . Can you please share working code

    ReplyDelete
  7. Helo, I am doing my project with spring mvc, I am configuring swagger 2 but in the swagger-ui.html# I show nothing, is anybody who could help me please?

    ReplyDelete