在 Swagger 中，map 类型参数用于表示一个键值对的集合，类似于 Java 中的 Map。map 类型参数在 API 文档中通常用于描述一组可选或动态的参数，使得接口更加灵活和可扩展。
Swagger map 使用场景
使用 Swagger 的 map 类型参数在以下场景中是有意义的：
- 当请求参数的数量不确定或动态变化时，可以使用 map 类型参数来接收任意多个参数。
- 当请求参数为可选参数时，可以使用 map 类型参数来接收一组可选参数。
- 当请求参数需要动态生成或根据条件进行调整时，可以使用 map 类型参数。
- 当需要传递一组键值对数据给后端服务时，可以使用 map 类型参数。
Swagger map 用法介绍
在 Swagger 中，使用 map 类型参数需要使用type: object和additionalProperties字段来表示。下面是一个使用 map 类型参数的示例：
parameters:
- name: params
in: body
description: 请求参数
required: true
schema:
type: object
additionalProperties:
type: string通过以上示例，可以通过params参数接收一个任意数量的键值对参数。
在 Swagger Editor 中的示例
下面是一个在 Swagger Editor 在线编辑器中运行的具体示例代码：
swagger: "2.0"
info:
title: Map Parameter Example
version: 1.0.0
servers:
- url: http://localhost:8080
paths:
/users:
post:
summary: Create a new user
consumes:
- application/json
parameters:
- name: user
in: body
required: true
schema:
type: object
additionalProperties:
type: string
responses:
200:
description: User created successfully在上面的示例中，我们定义了一个接口路径 /users，其中有一个 POST 请求来创建一个用户。我们定义了一个参数 user，它是一个 map 类型的对象，其中的键和值都是字符串类型。
你现在可以在 Swagger Editor 的界面上测试这个 API。在请求体中传递一个 JSON 对象，包含了你想要创建的用户信息。Swagger 会将这个参数解析为一个 map 类型的对象，并发送给目标服务器（在这个例子中是 http://localhost:8080）。
在 SpringBoot 中配置
假设我们用 SpringBoot 来开发一个用户管理的系统，其中有一个 API 接口来创建新用户。用户可以传递一个 Map<String, Object> 类型的参数，其中包含用户的姓名、年龄和电子邮件。我们可以使用 Swagger 来定义这个接口的参数。
我们创建一个名为 UserController 的控制器类，其中包含了一个 createUser 接口方法。
@RestController
@Api(tags = "User Controller", description = "APIs for User Management")
public class UserController {
@ApiOperation("Create a new user")
@PostMapping("/users")
public ResponseEntity<String> createUser(
@ApiParam(value = "User details", required = true) @RequestBody Map<String, Object> user) {
// 从传入的 user Map 中获取姓名、年龄和电子邮件
String name = (String) user.get("name");
int age = (int) user.get("age");
String email = (String) user.get("email");
// 在这里执行创建用户的逻辑
// ...
return ResponseEntity.ok("User created successfully");
}
}在上面的示例中，我们使用了 Swagger 的 @ApiParam 注解，给 user 参数添加了说明。用户可以通过 Swagger UI 来测试这个 API，传递一个包含用户姓名、年龄和电子邮件的 JSON 对象作为 user 参数。
使用 Swagger 自动生成的 API 文档，在 Swagger UI 中就可以看到这个 API 的参数说明和示例请求。
例如，用户可以发送以下 POST 请求，在请求体中传递一个 JSON 对象来创建一个新用户：
POST /users
{
"name": "John Doe",
"age": 25,
"email": "john.doe@example.com"
}在用户传递的参数中，我们可以在控制器类中使用这些数据来执行用户创建的逻辑。
上述代码中，使用@RequestBody注解将请求参数映射为一个 Map<String， String>类型的参数。这样就可以在控制器方法中获取到传递的键值对参数。
注意事项
在使用 Swagger 的 map 类型参数时，需要注意以下几点：
- 由于 map 类型参数可以接收任意键值对参数，因此要确保接口逻辑能正确处理不同参数组合的情况。
- 如果使用了 map 类型参数，建议在接口文档中明确说明接收的参数格式和限制条件，以便开发者正确使用。
- 当需要限制 map 类型参数的键或值的数据类型时，可以使用
properties字段来定义具体的数据类型。
常见的问题与解决方案
1.如何传递多个键值对参数？
可以将多个键值对参数以 JSON 对象的形式传递给 map 类型参数。
2. 如何限制 map 类型参数的键或值的数据类型？
可以使用properties字段来定义具体的数据类型，例如properties: { key: { type: string }, value: { type: integer } }。
3. 如何在 SpringBoot 项目中正确接收 map 类型参数？
可以使用@RequestBody注解将请求参数映射为一个 Map<String， String>类型的参数。
Swagger 和 Apifox 整合
Swagger 管理接口有时很不方便，缺乏一定的安全性和团队间的分享协作，所以我更推荐使用 Apifox 的 IDEA 插件。你可以在 IDEA 中自动同步 Swagger 注解到 Apifox，一键生成接口文档，多端同步，非常方便测试和维护，这样就可以迅速分享 API 给其他小伙伴。
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-and-maps/