Spring Boot 005: Swagger 3.0 Implementation

Previous article: Spring Boot 004: Lombok

Hello. I’ll be introducing a simple yet great documentation tool called Swagger. If you’ve come across this article you probably know what Swagger is and simply wondering how to implement it or what more you can do with it. Just hang on, this one gonna be quick. Well, at least for you.

logo

0. About

The official website defines Swagger as a tool that allows you to describe the structure of your APIs so that machines can read them. The ability of APIs to describe their own structure is the root of all awesomeness in Swagger. Why is it so great? Well, by reading your API’s structure, it can automatically build beautiful and interactive API documentation. It can also automatically generate client libraries for your API in many languages and explore other possibilities like automated testing.

So let’s dig in.

1. Implementation

Add the following dependencies to the project’s pom.xml file.

<!--Swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
<!--Swagger-->

To enable Swagger, you need to create a Configuration class as such:

@Configuration
public class SwaggerConfig {
  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        // .apis(RequestHandlerSelectors.any())
        .apis(RequestHandlerSelectors.basePackage("com.tahaburak.atem.controller"))
        .paths(PathSelectors.any())
        .build();
  }
}

• By pointing the package of controllers, we’re preventing Swagger to list default controllers implemented by Spring itself.

So let’s run the application and visit the following URL on the browser.

http://localhost:2836/swagger-ui/index.html

Swagger 3 UI

Swagger UI is up and ready 🙂

1. 1 — Swagger 2 Implementation

In case you wonder how to implement all you need to is change dependencies as following:

<!--Swagger-->
<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>
<!--Swagger-->

To enable Swagger, you need to add the “@EnableSwagger2” annotation to the configuration class.

@Configuration
@EnableSwagger2
public class SwaggerConfig {
  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        // .apis(RequestHandlerSelectors.any())
        .apis(RequestHandlerSelectors.basePackage("com.tahaburak.atem.controller"))
        .paths(PathSelectors.any())
        .build();
  }
}

However, Swagger 2 publish interface to another URL:

http://localhost:2836/swagger-ui.html

Swagger 2 UI

By simply adding dependencies and a Configuration class we’ve successfully implemented Swagger. Let’s look into the Documentation part.

2. Documentation

Well, it’s relatively easy to document an endpoint via Swagger. Following code block documents what’s the purpose of the endpoint getUserById and its possible responses.

Swagger documentation for endpoint getUserById

Swagger documentation for endpoint getUserById

Swagger will expose the endpoint as such:

3. Request Execution

Swagger UI let’s users to make request through itself. By simply pressing “Try it out” button on any endpoint it’ll show input for the endpoint if there’s. After filling the input simply press the “Execute” button.

Service request example through Swagger UI

4. Conculision

Swagger provides a lot more of features, customization tools etc. I’m planning to publish another article on this matter. Until then following resources might be helpful.

Setting Up Swagger 2 with a Spring REST API | Baeldung

Documenting a Spring REST API Using OpenAPI 3.0 | Baeldung

Spring Boot RESTful API Documentation With Swagger 2 - DZone Integration

You can find the source code at Github.

Sincerely,
Burak.