使用自定义注解增强 Swagger 文档

在前一节中，我们学习了 API 文档。我们看到了 Swagger 文档的高级概述结构。在本节中，我们将自定义 Swagger 元素的 info。 Swagger 注解在 swagger-annotations-1.5.20.jar 文件中定义。

步骤 1： 打开 SwaggerConfig.java。

步骤 2： 创建一个类型为 ApiInfo 的常量 DEFAULT_API_INFO。

步骤 3： 按住 ctrl 键并单击常量类型 (ApiInfo)。 ApiInfo 类将打开。

步骤 4： 从该类复制两个常量 DEFAULT _CONTACT 和 DEFAULT 。或复制以下代码并将其粘贴到 SwaggerConfig.java 中。将常量 DEFAULT 重命名为 DEFAULT_API_INFO。

步骤 5： 配置开发人员或组织的联系方式。

步骤 6： 配置 DEFAULT_API_INFO。在此配置中，提供我们想要在 Swagger 文档中显示的所有信息。

SwaggerConfig.java

步骤 7： 重启应用程序。

步骤 8： 打开浏览器并输入 URI https://:8080/v2/api-docs。它在文档中显示更新后的联系方式和 API 信息。

接受和生成 XML 格式

我们应该更明确地说明我们产生什么和消费什么。因此，在下一步中，我们将添加内容协商。我们可以接受 application/json 或 application/xml 格式的输入，并生成 application/json 或 application/xml 格式的响应。

让我们在我们的项目中指定内容协商。

步骤 1： 在 SwaggerConfig.java 中，转到 Docket api() 并添加 .produces(DEFAULT_PRODUCES_AND_CONSUMES).consumes(DEFAULT_PRODUCES_AND_CONSUMES)。

步骤 2： 创建一个常量 DEFAULT_PRODUCES_AND_CONSUMES。

步骤 3： 创建一个 HashSet 并添加两个值 application/json 和 application/xml。

请注意，我们不能直接将值传递给 HashSet。所以我们将一个 List 传递给 HashSet 的构造函数。

SwaggerConfig.java

步骤 4： 打开浏览器并输入 URI https://:8080/v2/api-docs。

上图表明它消费和生成 JSON 和 XML 格式。

我们可以添加更多关于用户模型的描述，例如出生日期必须是过去的日期，姓名必须至少包含五个字符等。让我们在 User 模型中添加更多描述。

步骤 1： 打开 User.java 并在类名上方添加 @ApiModel 注解。添加关于 User 模型的描述。

@ApiModel： 它提供关于 Swagger 模型的附加信息。

我们添加了以下描述

步骤 2： 在 dob 变量上方添加另一个注解 @ApiModelProperty。

@ApiModelProperty： 它允许控制特定于 Swagger 的定义，例如值和附加注释。

步骤 3： 类似地，为 name 变量添加 @ApiModelProperty 注解。

User.java

步骤 4： 重启应用程序。

步骤 5： 打开浏览器并输入 URI https://:8080/v2/api-docs。如果我们查看 User 模型的描述，我们会发现我们指定的描述出现在这里。

API 文档与 API 同样重要。我们的服务的消费者不应该有任何关于如何消费服务、有哪些不同的细节、输出是什么样子的疑问等。一切都应该对消费者清楚，以便用户可以轻松理解。

因此，Swagger 文档对服务的消费者是有益的。 Swagger 提供了许多可用于增强模型、操作和 Swagger 配置的注解。