Swagger With Play2

What is Swagger :

Swagger is very powerful tool for REST API description and API documentation.Swagger API gives a Swagger GUI for humans to learn and test your API.It’s 100% open source.The goal of Swagger is to enable client and documentation systems to update at the same pace as the server. The documentation of methods, parameters, and models are tightly integrated into the server code, allowing APIs to always stay in sync.
In this post I’m going to show step by step instruction how to setup Swagger UI with Play Framework.
How to Use Swagger Api In Our Project:-

———————————————————————————————————————–
Step-1: Installing swagger-play2 plugin:

Just Add Swagger dependency to your project’s dependencies (most likely in build.sbt)

—————————————————————————————————————————–
Step-2 :For Swagger UI

2.1:Download Swagger UI:

Download Swagger UI and put all these files in [project_root_dir]/public/swagger
—————————————————————————————————————————–
Step-2.2:For Getting swagger home page:

Copy index.html in [project_root_dir]/app/views and rename it in swagger.scala.html
———————————————————————————————————–
Step-2.3: Modify Swagger.scala.html:

Follow next three steps for modifying swagger.scala.html
a): Introduce one import statement in swagger.scala.html:

Add following line on the top of the file:

b) Update all src location in swagger.scala.html:
Update all src location .After updating all of them would be like this:

c) Update some java script code in swagger.scala.html:

Update JavaScript code snippet by injecting there some Play Template code:

——————————————————————————————————-
Step-3 : Import following for decorating our action :

For necessary annotation to decorate action,use following import:

It’s time to decorate REST endpoints with appropriate annotations:

——————————————————————————————————–
Step-4 :Modification in routes.scala

Step-4.1: Add a route in routes.scala for listing end points :

In routes file ,put following URI in order to list all REST endpoints in a project:

————————————————————————————————————-
Step-4.2 : Add Swagger api-docs routes for each end points in routes.scala:
Modify routes file again but now for a particular endpoint:

—————————————————————————————————
Step-4.3 : Add a route in routes.scala for getting swagger UI :

finally add following routes

—————————————————————————————————————————-
Step-5 Add an Action in Application.scala for getting Swagger-GUI :

Add an action which will be responsible for Swagger UI display:

————————————————————————————————————————–
Step-6:Add application URL for Swagger GUI in application.conf:

Add default application URL in application.config

———————————————————————————————————————-

#Verify the Swagger API Configuration :
Check Swagger-api’s configuration at – http://localhost:9000/api-docs.json
If all things went good then there would be response like this :
{“apiVersion”:”beta”,”swaggerVersion”:”1.2″,”apis”:[{“path”:”/hello”,”description”:”Some operation like GET,POST and Upload Image”}]}

Check following image:

SwaggerApiDocResponse

http://localhost:9000/api-docs.json – doesn’t respond than something went wrong.

#How to run my swagger UI:
Run your project with all services(if exists) after it
check the Swagger API Docs at http://localhost:9000/swagger
SwaggerUI

There is only one link named hello because in routes.scala,there was one route named hello.

Just click on hello link and see all your rest api link associated with hello.

SwaggerRoutesLink

#How to check Api Response:

There are 3 routes.

Just click POST/hello/{name} :-   It takes name as a query parameter and nick_name and address as a Json. Click on Try it out!  and check next image:

SwaggerPOSTResponse

#For Image Upload :

For uploading an image as well as send data through form.

SwaggerUploadImage

Github link for demo project : Swagger_Play

6 thoughts on “Swagger With Play2

  1. If you are using Scala 2.11.6, Play v2.4.x you will need to have these items.
    build.conf:
    “io.swagger” %% “swagger-play2” % “1.5.0”

    application.conf:
    play.modules.enabled += “play.modules.swagger.SwaggerModule”

    Without the line in application.conf you will get a NPE when trying to access the /api-docs.json

    1. Thank you John!

      If you get a play.modules.swagger.SwaggerModule not found message, make sure you replace the double quotes with “plain” double quotes (do not copy-past the above lines).

Leave a Reply

%d bloggers like this: