Setup Swagger Configuration in SpringBoot

Swagger according to wikipedia,

Swagger is an Interface Description Language for describing RESTful APIs expressed using JSON. Swagger is used together with a set of open-source software tools to design, build, document, and use RESTful web services. Swagger includes automated documentation, code generation, and test-case generation.

It’s a way of exposing your restful apis to your frontend developers to consume the apis.

To setup swagger in SpringBoot application. There are various steps you have to follow.

A. Add Swagger Dependencies

1. You need to create a new SpringBoot application from spring.io, if you don’t have an existing application.
2. Add the following dependencies: devtools, starter web, maybe jpa and h2 as you may need for your particular project.

Generate and extract the project into your working folder and open the project in any IDE of you choice. STS, IntelliJ, Netbeans, etc

3. For your newly created or existing application, open the pom.xml file and add the following dependencies again.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

As of the time of this write-up, version 2.9.2 was the latest.

B. Create Swagger Config Class

1. Create a new package and name it config
2. Create a new class in the config package and name it “SwaggerConfig”

3. Tell SpringBoot that it is going to be a configuration file by adding the @Configuration annotation

4. Enable Swagger in the SwaggerConfig Class by adding the @EnableSwagger2 annotation

5. Create a Bean in the SwaggerConfig file

Reload the application and open the browser then

6. visit http://localhost:8080/v2/api-docs for the documentation

7. visit http://localhost:8080/swagger-ui.html for a visual representation

This will show all the controllers that had been created and the operations that had been created in each of them.

the operations I have created in the user-controller

C. Swagger API Doc (Explained)

There are various elements in the swagger api doc such as

1. Info: contains details about the api we have created,
2. Host: where the api is hosted
3. basePath: just like the name, its the base path to the service, so, if the basepath is /stlemmy/api then to call the service you have the host/basepat=> localhost:8080/stlemmy/api
4. tags: use to group the resources and resource methods and also group them into multiple categories
5. paths: shows the details of all the paths we are exposing, and the different operations that can be performed that we have created.
6. definitions: Shows different elements used in the api, such as the elements in the our User

D. Swagger Api Info Details Config

There are default swagger api info details provided after the configuration.

To change such info details, you can either create a new Bean ApiInfo or append apiInfo to the existing existing. I would use the append option.

Below is the default swagger api info details:

{“swagger”:”2.0",”info”:{“description”:”Api Documentation”,”version”:”1.0",”title”:”Api Documentation”,”termsOfService”:”urn:tos”,”contact”:{},”license”:{“name”:”Apache 2.0",”url”:”http://www.apache.org/licenses/LICENSE-2.0"}},

To update or change the Swagger Api Info details we would update the existing Docket Bean:

1. Create a variable and call it DEFAULT_API_INFO and append apiInfo(DEFAULT_API_INFO) to the the existing Docket.
2. Create a Contact DEFAULT_CONTACT and variable and fill in the details as it is in the ApiInfo Class
3. Update the ApiInfo Details to whatever you want the save.

Then reload the application and the browser and Swagger Api Info Details would have been updated.

E. Format

Additionally, you can define the format the is produced and consumed such as application/json which is the default but if you intent to also produce and consume xml, you can research on content negotiation and add this dependency

<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-xml</artifactId>
</dependency>

then you can send and receive xml.

So to tell, our SpringBoot application to produce and consume both json and xml you would need to update our existing Bean and add the configuration for “Produce and Consume”

This way the application can produce and consume both json and xml. But if you don’t want you application produce and consume both, then, you can skip this additional configuration.

F: Enhance The Application Documentation with Swagger

You can also enhance by add different Swagger annotations in your application such @ApiModel(description = “User Details Table”) on the User Class or model

@ApiModelProperty(notes = "Name should have at least 2 characters")
private String name;

On the model property or column name.

Reload the application and the browser then check the model for details provided on the model.

For more details about the Swagger annotations you can check the jar under swagger annotations.

Thank you.