知識庫 / REST RSS 訂閱

1. 概述

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

2. API 描述

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

3. Swagger 2

為了使用 Swagger 2 為 Spring Boot REST API 構建 API 文檔，我們可以使用 Springfox 庫。我們需要在 pom.xml 文件中添加 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 = "")

然而，正如前面提到的，<strong >描述 (description) 屬性已棄用</strong >。 幸運的是，有替代方案。我們可以使用 <strong >標籤 (tags) 屬性</strong >：

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

在 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"));
    }

}

在這裏，我們使用 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 的最新版本規範。它是 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. 結論

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