Swagger additionalProperties 如何使用

在 Swagger 中，additionalProperties 是一个用于描述模型中包含未在属性列表中定义的额外属性的选项。它允许接受任意的一个或多个键值对。它的作用是为了在模型定义中包含未知或动态属性。通常，在设计 API 时，我们无法预先知道 API 用户会传递什么样的额外属性，这时就可以使用 additionalProperties 功能来灵活地处理这些未知属性。

additionalProperties 使用场景

下面列举一些常见的使用场景，以帮助你确定 additionalProperties 是否适合你的项目：

接受自定义参数：允许 API 用户传递额外的参数，以满足他们特定的需求。
动态属性扩展：支持动态扩展属性，以便满足未来需求的变化。
附加元数据：将额外的元数据附加到 API 响应中，以便客户端能够根据需要进行后续的处理。

additionalProperties 用法

在 Swagger 规范中，你可以在模型定义的 "properties" 部分使用 additionalProperties 字段来设置该模型是否允许接受额外属性。其语法形式如下：

properties:
  property_name:
    type: property_type
  ...
additionalProperties: true/false

如果 additionalProperties 被设置为 true，这意味着模型可以接受任意的额外属性，并且不会对其进行类型验证。
如果 additionalProperties 被设置为 false，这意味着模型不允许接受额外的属性。
如果 additionalProperties 被设置为一个对象，这将被视为额外属性的模型定义，并且将对额外属性进行类型验证。
此外，你还可以在 additionalProperties 中设置更多的属性，以对额外属性进行进一步的限制，例如类型、格式、枚举值等。以下是一个使用 additionalProperties 的示例：

properties:
  name:
    type: string
  age:
    type: integer
additionalProperties:
  type: string

上述示例定义了一个模型，包含 "name" 和 "age" 两个属性，并允许接受任意的额外属性，但是这些额外属性必须是字符串类型。

additionalProperties 实践案例

下面是一个在 Swagger Editor 中运行的示例代码，演示了如何使用 additionalProperties 功能。

swagger: '2.0'
info:
  title: Example API
  version: 1.0.0
paths:
  /example:
    post:
      summary: Example endpoint
      parameters:
        - in: body
          name: body
          schema:
            type: object
            additionalProperties:
              type: string
            example:
              name: John Doe
              age: 30
      responses:
        '200':
          description: OK

上述示例定义了一个名为 "Example API" 的 API 文档，其中包含一个 POST 请求的示例端点 /example。在请求体参数中，定义了一个类型为 object 的模型，并使用 additionalProperties 配置允许接受任意的键值对。

在 SpringBoot 项目中配置

要在 SpringBoot 项目中配置 additionalProperties 功能注解，你可以使用 Swagger 注解 @ApiModel，配合 @ApiModelProperty 注解来设置属性的 additionalProperties。在模型类中使用 @ApiModelProperty 注解来标识需要支持 additionalProperties 的属性。

@ApiModel(additionalProperties = true)
public class ExampleModel {
    @ApiModelProperty(example = "John Doe")
    private String name;
    @ApiModelProperty(example = "30")
    private int age;
    // other properties and methods
}

注意事项

使用 additionalProperties 功能时，需要注意以下事项：

额外属性的类型限制：在使用 additionalProperties 时，默认情况下不会对额外属性进行类型验证。如果需要验证额外属性的类型，可以在 additionalProperties 中定义数据类型。
缺少属性校验：如果不定义属性列表，并且设置 additionalProperties 为 false，那么将不允许传递额外的属性。

更好的解决方案

Swagger 管理接口有时很不方便，缺乏一定的安全性和团队间的分享协作，所以我更推荐使用 Apifox 的 IDEA 插件。你可以在 IDEA 中自动同步 Swagger 注解到 Apifox，一键生成接口文档，多端同步，非常方便测试和维护，这样就可以迅速分享 API 给其他小伙伴。

立即体验 Apifox

Apifox 是一个比 Postman 更强大的接口测试工具，Apifox = Postman + Swagger + Mock + JMeter，Apifox 支持调试 http（s）、WebSocket、Socket、gRPC、Dubbo 等协议的接口，并且集成了 IDEA 插件。

Apifox 的 IDEA 插件可以自动解析代码注释，并基于 Javadoc、KDoc 和 ScalaDoc 生成 API 文档。通过 IntelliJ IDEA 的 Apifox Helper 插件，开发人员可以在不切换工具的情况下将他们的文档与 Apifox 项目同步。

当在 IDEA 项目中有接口信息变动，只需右键点击「 Upload to Apifox」一键即可完成同步，无需奔走相告。团队成员可在 Apifox 中看到同步后的最新内容。

现在出发去 JetBrains 插件市场下载试试吧！或直接在 IDEA 内「plugin」入口直接搜索 Apifox Helper。

知识扩展：

参考链接：

Swagger 官方文档：https://swagger.io/docs/specification/data-models/dictionaries/