Swagger with Spring Boot and Security

Documentation is too important in projects where different teams involved in such as, front-end and back-end developers. Especially, when building RESTful web services, possible third party consumers will may increase unpredictably. In order to make REST API more clear and understandable, there are documentation solutions and Swagger is one of them. Swagger is used to document REST API with user friendly interface via web browsers.

In order to use Springfox implementation of Swagger in Spring Boot projects, below dependencies must be added to pom.xml.

“springfox-boot-starter” dependency is used to generate API docs. “swagger-ui” is used to display this documentation in pretty way and also it provides interaction between users and API endpoints on the browser.

After adding dependencies to pom.xml, a Configuration class must be added to project as seen below. Docket bean, which is responsible for configuration, must be defined in this class.

Packages which are wanted to be scanned in the project, can be defined with “RequestHandlerSelectors”. You may want to add just controller classes in swagger, or may want to add also Entity classes.

ApiInfo is optional to be added, and it provides extra information about REST API documentation, such as title, description and contact info.

That is all has to be done, dependencies and Docket Bean definitions are enough for swagger-ui for REST API docs. In order to make API doc more readable and informative, “@Api” and “@ApiOperation” annotations can be added to controller classes and endpoints.

Note that, you can also get more information about Entity fields by adding “@ApiModelProperty” annotation.

Swagger-ui is ready to publish at below path:

http://localhost:8080/${app-root}/swagger-ui/

Here is the main page of REST API doc powered by swagger. As seen, endpoints of Project controller class have been listed. Also, Entity models can be found at the bottom of the page.

At swagger-ui page, endpoints can also be called and response that returns from API can be checked. “Try it out” sample will be shown in the next part which is about security usage.

Beside endpoints, Entity and attributes can also be seen. As seen below, “validation” of attributes also added to model. With @NotNull and @Size annotations, “projectName” is marked as required and “projectCode” size declared to be between 0 and 5.

Swagger with Spring Security

Swagger-ui can be used with above configuration, but if REST API is not secured. As known, using web services as insecure is a bit rare condition. So, in this part we will see how to configure swagger with security.

In order to access swagger-ui path on browser, it should be added to permission list. Swagger related paths, as shown below, must be added to your configuration class which extends “WebSecurityConfigurerAdapter” and should be permitted.

Note that, you can check both “http://localhost:8080/${app-root}/v3/api-docs” and “http://localhost:8080/${app-root}/v2/api-docs”. v3 is in openapi 3.0 and v2 is in swagger2 format.

Adding swagger related paths to permission list is enough to access “swagger-ui” page. Controller classes with endpoints and Entity models can be seen on the browser as seen before above.

In order to access and call endpoints of REST API, SecurityContext and SecurityScheme must also be added to Docket Bean.

Sample definitions of SecurityScheme and SecurityContext can be seen below. SecurityScheme is used to describe how to secure REST API, in this sample JWT will be used.

That is it, you can call endpoints on swagger in secured REST APIs as well. There is a new “Authorize” button on swagger-ui page, which should be used before calling endpoints.

By clicking “Authorize” button, a pop-up dialog will open and you can write your token here for authentication. After successful authentication, endpoints can be called.

This is how “try it out” an endpoint. By “executing” the API call, it adds token to authorization header. JSON returns from API endpoint can be seen as Response Body.

Note that, you can use Basic Authentication or OAuth instead of Bearer token.

Hope, it will be helpful…