1. 概述
描述 RESTful API 在文档中起着重要作用。用于记录 REST API 的一种常用工具是Swagger 2 。然而，用于添加描述的一个有用属性已被弃用。在本教程中，我们将使用 Swagger 2 和OpenAPI 3找到已弃用的 描述 属性的解决方案，并且我们将展示如何使用它们来描述Spring Boot REST API 应用程序。
2. 接口说明
默认情况下，Swagger 会为 REST API 类名称生成空描述。因此，我们必须指定一个合适的注释来描述 REST API。我们可以将 Swagger 2 与 @Api 注释一起使用，也可以在 OpenAPI 3 中使用 @Tag 注释。
3. 招摇2
要将 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>
Springfox库提供 @Api 注释来将类配置为Swagger资源。此前， @Api 注解提供了 description 属性来自定义API文档：
@Api(value = "", description = "")
然而，如前所述， description 属性已被弃用 。幸运的是，还有一个替代方案。我们可以 使用 标签 属性 ：
@Api(value = "", tags = {"tag_name"})
在 Swagger 1.5 中，我们将使用 @SwaggerDefinition 注解来定义 标签 。但是，Swagger 2 中不再支持它。因此，在 Swagger 2 中，我们在 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"));
}
}
在这里，我们使用 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.开放API 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 来实现这一点。对于 Swagger 部分，代码可在 GitHub 上找到。要查看 OpenAPI 3 示例代码，请在 GitHub 上查看其模块。