Swagger @Api Description Is Deprecated

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.