@Schema中参数allowableValues 详解

在 @Schema 注解中，allowableValues 参数用于指定接受的值的范围，它可以用于枚举类型或者字符串类型的属性。该参数需要传入一个字符串数组，每个字符串都是一个有效的取值。如果在API文档中，用户输入的值不在可接受范围内，将会返回一个 400 Bad Request 错误。

例如，假设有一个请求体参数名为 gender，只接受 male 和 female 两个值，那么可以在对应的DTO类的 gender 字段上加上 @Schema 注解，并设置 allowableValues 参数为 {"male", "female"}。这样，在API文档中，用户在 gender 字段中输入其他值时，就会提示用户输入 male 或者 female。

示例代码如下：

public class UserDTO {
    @Schema(description = "性别", allowableValues = {"male", "female"})
    private String gender;
    
    // getter 和 setter
}

相关问题

@Schema 注解 参数详解

@Schema 注解是 OpenAPI 规范中的一部分，用于描述 API 的数据模型（数据结构）。该注解可以应用于类、属性、方法等上面。

下面是 @Schema 注解中常用的参数及其含义：

- name：指定该字段在 API 文档中的名称。
- title：指定该字段在 API 文档中的标题。
- description：指定该字段在 API 文档中的描述。
- format：指定该字段的数据格式，如日期格式等。
- type：指定该字段的数据类型，如字符串、整数、布尔值等。
- example：指定该字段的示例值，用于说明该字段的取值范围。
- defaultValue：指定该字段的默认值。
- accessMode：指定该字段的访问权限，可选值为 READ_ONLY、READ_WRITE、WRITE_ONLY。
- nullable：指定该字段是否可以为 null。
- required：指定该字段是否为必填字段。
- readOnly：指定该字段是否只读。
- writeOnly：指定该字段是否只写。

需要注意的是，@Schema 注解的参数可能因为不同的使用场景而有所不同，具体使用方式可以参考 OpenAPI 规范的相关文档或者具体的使用示例。

@Parameter中schema参数详解

在 OpenAPI 规范中，`@Parameter` 注解的 `schema` 参数用于定义参数的数据类型和格式，可以使用各种数据类型、格式和约束来描述参数。

下面是一些常见的 `schema` 参数选项：

- `type`：参数的数据类型，可以是数字、字符串、布尔值、数组等。常见的类型有 `integer`、`number`、`string`、`boolean`、`array` 等。
- `format`：参数的数据格式，例如日期、时间、日期时间、邮箱、URL 等。常见的格式有 `date`、`time`、`date-time`、`email`、`uri` 等。
- `enum`：参数的枚举值，用于限制参数的取值范围。例如，`enum: [red, green, blue]` 表示参数只能取 `red`、`green` 或 `blue` 中的一个值。
- `minimum` 和 `maximum`：参数的最小值和最大值。仅适用于数值类型的参数。
- `minLength` 和 `maxLength`：参数的最小长度和最大长度。仅适用于字符串类型的参数。
- `pattern`：参数的正则表达式模式，用于限制参数的格式。

除了上述选项外，还有一些高级选项可以用于描述参数的约束和格式，例如 `multipleOf`、`exclusiveMinimum`、`exclusiveMaximum` 等。

示例：

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get a list of users
      parameters:
        - in: query
          name: status
          schema:
            type: string
            enum: [active, inactive]
          description: Filter users by status
      responses:
        '200':
          description: OK

在上面的示例中，`status` 参数是一个字符串类型的参数，它的取值范围被限制为 `active` 或 `inactive`。通过 `schema` 参数，我们可以非常灵活地定义各种类型的参数，以及它们的格式、约束和限制。