1. 概述
在这个教程中，我们将简要介绍Swagger的@Parameter和@Schema注解。此外，我们将比较这些注解，并确定每种注解的正确用法。
2. 主要区别
简单来说，@Parameter和@Schema注解为Swagger添加了不同的元数据。@Parameter用于API资源请求的参数，而@Schema则用于模型的属性。
3. @Parameter
@Parameter注解用于定义操作或路径参数部分的参数。@Parameter注解有助于指定参数的名称、描述和示例值。此外，我们可以指定参数是必需的还是可选的。
让我们看一个使用示例：
@RequestMapping(
method = RequestMethod.POST,
value = "/createUser",
produces = "application/json; charset=UTF-8")
@ResponseStatus(HttpStatus.CREATED)
@ResponseBody
@Operation(summary = "Create user",
description = "This method creates a new user")
public User createUser(@Parameter(
name = "firstName",
description = "First Name of the user",
example = "Vatsal",
required = true)
@RequestParam String firstName) {
User user = new User(firstName);
return user;
}
现在，让我们看看Swagger UI对我们的@Parameter示例的表示：
接下来，我们来看@Schema。
4. @Schema
@Schema注解允许我们控制Swagger特定的定义，如描述、名称、类型、示例值以及模型属性的允许值。此外，如果在某些场景下希望隐藏属性，它还提供了额外的过滤属性。
让我们在User模型的firstName字段上添加一些属性：
@Schema(
description = "first name of the user",
name = "firstName",
type = "string",
example = "Vatsal")
String firstName;
现在，让我们看看Swagger UI中User模型的规格：
5. 总结
在这篇简短的文章中，我们探讨了两种可以为参数和模型属性添加元数据的Swagger注解。然后，我们通过示例代码展示了这些注解的用法，并在Swagger UI中查看了它们的表示。
一如既往，所有这些代码示例可在GitHub上找到。