Install Swagger in Java – Jersey 2 Project

Documenting a rest service can be very extensive. Another problem is that every change to the rest service caused an outdated documentation. And the updating of documentation is quickly forgotten.

There is where Swagger.io comes in. The documentation with swagger works with annotations which are added to the rest methods. Therefore its very difficult not to update the Documentation by changing the REST API.

How to add and configure swagger.io into your java project will be explained in this article.

(This article covers a Setup for JAX-RS Jersey2. Its possible so setup Swagger with JAX-RS jersey 1 and RESTEasy. More informations here.)

Hooking up Swagger-Core in our Application

To use swagger in your project you have to add this dependencies in your pom.

Initialize and Configure Swagger

I am using a Application class for my rest service. Swagger’s BeanConfig class allows you to set various properties for Swagger’s initialization. The Configuration looks like this:

It is possible to initialize Swagger with a servlet too. For more informations look here.

Add Documentation to your REST service

There are a few annotations with wich you can document your rest service. A complete documentation with examples can be found here.

Here my example:

Add Swagger UI to your project

At this point you have a JSON based documentation. You can verify it by open the url (in our case) http://localhost:8080/api/swagger.json:

This JSON File is hard to read. With the Swagger UI we have a tool to display the documentation in a better way. To get a better display of the Documentation we have to install the Swagger-UI Client in our Project or as a standalone Application.
First we have to download the Swagger-UI Client from here.

In our case i have put the Swagger-UI in the project webapp folder by only unzipping it.

The Swagger-UI has a default swagger.json File from the Swagger Demo Project. For our purposes we have to replace this url with our swagger.json.

By opening the Swagger-UI in our browser with this url http://localhost:8080/swagger/ we see this nice Documentation:

Bildschirmfoto 2016-05-03 um 15.35.14

My Demo Project can be downloaded on Github@swapover

Schreib einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.

Diese Website verwendet Akismet, um Spam zu reduzieren. Erfahre mehr darüber, wie deine Kommentardaten verarbeitet werden.

%d Bloggern gefällt das: