1. Overview

1.概述

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.

描述RESTful API在文档中起着重要作用。用于记录REST API的一个常用工具是Swagger 2。然而，一个用于添加描述的有用属性已被废弃。在本教程中，我们将使用Swagger 2和OpenAPI 3为被废弃的description属性找到解决方案，我们将展示如何使用这些属性来描述Spring Boot REST API应用程序。

2. API Description

2.API描述

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.

默认情况下，Swagger为REST API类名生成了一个空的描述。因此，我们需要指定一个合适的注解来描述REST API。我们可以使用Swagger 2的@Api注解，或者使用OpenAPI 3的@Tag注解。

3. Swagger 2

3. 斯瓦格 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:

要将Swagger 2用于Spring Boot REST API，我们可以使用Springfox库。我们需要在pom.xml文件中添加springfox-boot-starter依赖项。

<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:

Springfox库提供了@Api注解来配置一个类作为Swagger资源。以前，@Api注解提供了一个description属性来定制API文档。

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

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

然而，如前所述，description属性已被废弃。幸运的是，有一个替代品。我们可以使用tags属性。

@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:

在Swagger 1.5中，我们会使用@SwaggerDefinition注解来定义tag。然而，它在Swagger 2中不再被支持。因此，在Swagger 2中，我们在Docket Bean中定义tags和descriptions。

@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:

这里，我们在Docket Bean中使用Tag类来创建我们的tag。有了这个，我们就可以在控制器中引用tag。

@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

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:

OpenAPI 3是OpenAPI规范的最新版本。它是OpenAPI 2（Swagger 2）的继承者。对于使用OpenAPI 3描述API，我们可以使用@Tag注解。此外，@Tag注解提供了一个描述和外部链接。让我们来定义BookController类。

@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

5.总结

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.

在这篇简短的文章中，我们描述了如何在Spring Boot应用程序中的REST API中添加描述。我们研究了如何使用Swagger 2和OpenAPI 3来实现这一目标。对于Swagger部分，代码可在GitHub上找到。要查看OpenAPI 3的示例代码，请查看其模块在GitHub上。