1. 概述

描述 RESTful API 在文檔中起着至關重要的作用。 常用的工具之一是 Swagger 2。 但是，用於添加描述的有用屬性已被棄用。 在本教程中，我們將找到使用 Swagger 2 和 OpenAPI 3 解決 description 屬性被棄用方案，並展示如何使用這些方案來描述 Spring Boot REST API 應用程序。

2. API 描述

默認情況下，Swagger 會為 REST API 類生成一個空描述。因此，我們必須指定合適的註解來描述 REST API。我們可以使用 Swagger 2 中的 @Api 註解或在 OpenAPI 3 中使用 @Tag 註解。

3. Swagger 2

要使用 Swagger 2 為 Spring Boot REST API，我們可以使用 Springfox 庫。我們需要在 Springfox-boot-starter 依賴中添加 springfox-boot-starter：

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

Springfox 庫提供 @Api 註解來配置類作為 Swagger 資源。 以前，@Api 註解提供了 description 屬性來自定義 API 文檔：

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

但是，如前所述， description 屬性已棄用。 幸運的是，有替代方案。我們可以使用 tags 屬性：

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

在 Swagger 1.5 中，我們使用 @SwaggerDefinition 註解來定義 tag。 但是，它在 Swagger 2 中不再受支持。 因此，在 Swagger 2 中，我們定義 tags 和 descriptions 在 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"));
    }

}

在這裏，我們正在使用 Tag 類在 Docket bean 中創建我們的 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

OpenAPI 3 是 OpenAPI 的最新版本 Specification。它是 OpenAPI 2 (Swagger 2) 的後繼版本。 使用 OpenAPI 3 描述 API，我們可以使用 @Tag 註解。 此外，@Tag 註解還提供 description 和外部鏈接。 讓我們定義 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. 結論

在本文中，我們介紹瞭如何在 Spring Boot 應用程序中添加 REST API 的描述。我們探討了如何使用 Swagger 2 和 OpenAPI 3 實現這一目標。