Expand Authors Top

If you have a few years of experience in the Java ecosystem and you’d like to share that with the community, have a look at our Contribution Guidelines.

Expanded Audience – Frontegg – Security (partner)
announcement - icon User management is very complex, when implemented properly. No surprise here.

Not having to roll all of that out manually, but instead integrating a mature, fully-fledged solution - yeah, that makes a lot of sense.
That's basically what Frontegg is - User Management for your application. It's focused on making your app scalable, secure and enjoyable for your users.
From signup to authentication, it supports simple scenarios all the way to complex and custom application logic.

Have a look:

>> Elegant User Management, Tailor-made for B2B SaaS

November Discount Launch 2022 – Top
We’re finally running a Black Friday launch. All Courses are 30% off until the end of this week:

>> GET ACCESS NOW

November Discount Launch 2022 – TEMP TOP (NPI)
We’re finally running a Black Friday launch. All Courses are 30% off until the end of this week:

>> GET ACCESS NOW

1. Overview

Describing a RESTful API plays an important role in the documentation. One common tool used to document REST APIs is Swagger 2. However, one useful attribute used for adding a description has been deprecated. In this tutorial, we'll find a solution for deprecated description attribute using Swagger 2 and OpenAPI 3, and we'll show how these can be used to describe a Spring Boot REST API application.

2. API Description

By default, Swagger generates an empty description for the REST API class name. Therefore, we need to specify a suitable annotation for describing a REST API. We can either use Swagger 2, with the @Api annotation, or we can use the @Tag annotation in OpenAPI 3.

3. Swagger 2

To use Swagger 2 for the Spring Boot REST API, we can use the Springfox library. We'll need to add springfox-boot-starter dependency in the pom.xml file:

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

The Springfox library provides @Api annotation to configure a class as a Swagger resource. Previously, the @Api annotation provided a description attribute to customize the API documentation:

@Api(value = "", description = "")

However, as mentioned earlier, the description attribute is deprecated. Luckily, there's an alternative. We can use the tags attribute:

@Api(value = "", tags = {"tag_name"})

In Swagger 1.5, we would use the @SwaggerDefinition annotation for defining the tag. However, it's no longer supported in Swagger 2. Therefore, in Swagger 2, we define the tags and descriptions in the Docket bean:

@Configuration
public class SwaggerConfiguration {

    public static final String BOOK_TAG = "book service";

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
          .select()
          .apis(RequestHandlerSelectors.any())
          .paths(PathSelectors.any())
          .build()
          .tags(new Tag(BOOK_TAG, "the book API with description api tag"));
    }

}

Here, we're using the Tag class in our Docket bean for creating our tag. With that, we can reference the tag in our controller:

@RestController
@RequestMapping("/api/book")
@Api(tags = {SwaggerConfiguration.BOOK_TAG})
public class BookController {

    @GetMapping("/")
    public List<String> getBooks() {
        return Arrays.asList("book1", "book2");
    }
}

4. OpenAPI 3

OpenAPI 3 is the latest version of the OpenAPI Specification. It is the successor to OpenAPI 2 (Swagger 2). For describing an API using OpenAPI 3, we can use the @Tag annotation. Moreover, the @Tag annotation provides a description and also external links. Let's define the BookController class:

@RestController
@RequestMapping("/api/book")
@Tag(name = "book service", description = "the book API with description tag annotation")
public class BookController {

    @GetMapping("/")
    public List<String> getBooks() {
        return Arrays.asList("book1", "book2");
    }
}

5. Conclusion

In this brief article, we described how to add a description into a REST API in a Spring Boot application. We looked at how this can be accomplished using Swagger 2 and OpenAPI 3. For the Swagger section, the code is available over on GitHub. To see the OpenAPI 3 sample code, check out its module over on GitHub.

November Discount Launch 2022 – Bottom
We’re finally running a Black Friday launch. All Courses are 30% off until the end of this week:

>> GET ACCESS NOW

REST footer banner
Comments are closed on this article!