《swagger》 swagger + springboot 传递 对象参数, List,数组参数

本文详细介绍了如何使用Swagger工具配合SpringBoot RESTful风格API,处理对象、List或数组等参数的传递,包括@ApiOperation、@ApiImplicitParam和@ApiImplicitParams注解的使用示例。

Swagger是最受欢迎的REST APIs文档生成工具之一, 与springboot 的restful风格的api配合, 更是让你事半功倍.

传对象,传list或数组是常遇到的问题.

传递对象参数

	@ApiOperation(value="添加Client", notes="增加Client" )
	@ApiImplicitParam(name = "client", value = "client信息", required = true, dataType = "Client")
	@PutMapping("/save")
	public Client save(@RequestBody Client client) {
		return clientService.save(client);
	}

传递List参数

	@ApiOperation(value="添加权限", notes="增加权限" )
	@ApiImplicitParams({ 
        @ApiImplicitParam(name = "clientId", value = "客户端ID", required = true, paramType = "query",dataType = "String", defaultValue="1"),
      })
	@PutMapping("/save")
	public Boolean save(String clientId, @RequestParam(value = "powerClientIds") @ApiParam(value = "可被访问的clientId列表") List<String> powerClientIds) {
                ........
		return true;
	}

@ApiImplicitParam的详细介绍及使用示例:name(必需):指定参数的名称。
value(可选):对参数的简单描述。
dataType(必需):指定参数的数据类型。
paramType(必需):指定参数的类型,可以是path、query、body、header或form。
example(可选):指定参数的示例值。
required(可选):指定参数是否是必需的,默认为false。
defaultValue(可选):指定参数的默认值。

<think>嗯,用户现在问的是Spring Boot应该如何接受上面提到的Retrofit处理List<String>参数的几种情况。之前用户的问题是关于Retrofit如何发送List类型的参数,现在转向了服务端的Spring Boot如何接收这些参数。我需要先回顾一下之前提供的四种方法,然后对应到Spring Boot中的处理方式。 首先,用户可能是在开发一个前后端分离的应用,前端使用Retrofit发送请求,后端Spring Boot处理。用户需要确保后端能正确解析前端发送的不同参数格式。比如,第一种情况是多同名查询参数,比如tags=android&tags=kotlin,这时候Spring Boot需要用@RequestParam来接收列表。第二种情况是逗号分隔的参数,比如tags=android,kotlin,这时候需要手动拆分字符串为列表。第三种是动态参数名,比如filter[tags]=android,可能需要用@RequestParam Map或者对象来接收。第四种是自定义处理,可能涉及自定义转换器。 接下来要考虑用户可能的背景。用户可能对Spring Boot有一定的了解,但不太清楚如何处理不同格式的列表参数。他们可能遇到的问题包括参数无法正确绑定到控制器方法中的列表,或者特殊格式的参数处理不正确。需要给出具体的示例代码,说明每种情况如何在后端处理。 另外,用户提到的Retrofit处理方式中有特别注意事项,比如空列表处理、URL编码、参数顺序等,这些在Spring Boot中也需要对应的处理方式。比如,如果前端发送空列表,可能需要设置required=false或者默认值。URL编码方面,Spring Boot默认会解码参数,但可能需要配置或使用@Encoded类似的注解,不过Spring中可能需要不同的处理。 需要确保回答结构清晰,分点对应之前的四种情况,以及注意事项。可能需要检查Spring Boot中处理列表参数的注解和配置是否正确,比如@RequestParam是否支持列表,是否需要使用数组还是列表类型。同时,对于逗号分隔的参数,可能需要自定义转换器或使用split方法。 可能还需要提到Spring Boot中的@GetMapping或@PostMapping对应的参数绑定方式,以及如何处理不同类型的请求参数。例如,对于查询参数、表单参数或路径参数的不同处理方式。但用户的问题主要聚焦在查询参数,所以重点在@RequestParam的使用。 此外,用户可能希望知道如何验证这些参数,或者处理异常情况,比如参数格式错误。但当前问题可能更关注基本接收方式,所以可能在注意事项中提到这些点。 最后,要确保示例代码正确,比如使用Java还是Kotlin。用户之前的Retrofit示例是Kotlin,但Spring Boot通常使用Java,不过可能用户也在用Kotlin。需要确认,但可能用Java更通用,或者两者兼顾。但用户现在的问题没有指定,所以可能使用Java示例,或者注明语言。 总结回答的结构: 1. 对应Retrofit的四种方式,分别说明Spring Boot如何接收。 2. 每种情况的代码示例,如@RequestParam List<String>。 3. 注意事项,如空列表、URL编码、参数校验等。 4. 可能的常见问题和解决方案。 需要检查Spring Boot是否默认支持多同名参数绑定到列表,可能需要确认。比如,Spring MVC中,使用@RequestParam List<String> tags会自动收集同名参数的值到列表,这是标准做法。对于逗号分隔的,需要手动处理,或者使用自定义转换器。动态参数名可能需要用Map或者对象封装。自定义处理可能需要Converter或Formatter。 确保回答准确,并且覆盖用户提到的所有情况,同时给出正确的代码示例和配置建议。避免可能的错误,比如参数名是否正确,是否需要使用@ModelAttribute等。保持回答简洁,但涵盖关键点。</think>在 Spring Boot 中接收 Retrofit 发送的 `List<String>` 类型参数,需要根据前端参数传递方式选择对应的接收策略。以下是 **4 种常见场景的对接方案**及具体实现: --- ### 一、接收多同名查询参数(默认方式) **前端格式**:`?tags=android&tags=kotlin` **Spring Boot 接收方式**:直接使用 `@RequestParam` + `List<String>` ```java @GetMapping("/posts/filter") public List<Post> filterPosts( @RequestParam("tags") List<String> tags, // 自动收集同名参数 @RequestParam(defaultValue = "1") int page ) { // 处理逻辑 } ``` **Kotlin 版本**: ```kotlin @GetMapping("/posts/filter") fun filterPosts( @RequestParam("tags") tags: List<String>, @RequestParam(defaultValue = "1") page: Int ): List<Post> { // 处理逻辑 } ``` --- ### 二、接收逗号分隔参数 **前端格式**:`?tags=android,kotlin` **Spring Boot 接收方式**:手动拆分字符串 ```java @GetMapping("/posts/filter") public List<Post> filterPosts( @RequestParam("tags") String tagsString // 接收原始字符串 ) { List<String> tags = Arrays.asList(tagsString.split(",")); // 手动拆分 // 处理逻辑 } ``` **Kotlin 优化版**: ```kotlin @GetMapping("/posts/filter") fun filterPosts( @RequestParam("tags") tags: List<String>? // 需配置自定义Converter ): List<Post> { // 处理逻辑 } // 配置全局Converter(将逗号分隔字符串转为List) @Configuration class WebConfig : WebMvcConfigurer { override fun addFormatters(registry: FormatterRegistry) { registry.addConverter(String::class.java, List::class.java) { source -> source.split(",") } } } ``` --- ### 三、接收动态参数名 **前端格式**:`?filter[tags]=android&filter[tags]=kotlin` **Spring Boot 接收方式**:使用 `@RequestParam Map` 或 DTO 对象 ```java // 方式1:通过Map接收 @GetMapping("/posts/filter") public List<Post> filterPosts( @RequestParam Map<String, String> params ) { List<String> tags = params.entrySet().stream() .filter(e -> e.getKey().startsWith("filter[tags]")) .map(Map.Entry::getValue) .collect(Collectors.toList()); } // 方式2:通过DTO对象接收 public class FilterDTO { private List<String> tags; // Getter需特殊命名匹配参数格式 @JsonProperty("filter[tags]") public List<String> getTags() { return tags; } } @GetMapping("/posts/filter") public List<Post> filterPosts(@ModelAttribute FilterDTO filter) { // 直接使用filter.getTags() } ``` --- ### 四、接收自定义编码参数(高级场景) **前端格式**:`?tags=android|kotlin` 或特殊编码格式 **Spring Boot 接收方式**:自定义 `Converter` ```java // 定义自定义Converter public class CustomListConverter implements Converter<String, List<String>> { @Override public List<String> convert(String source) { return Arrays.asList(source.split("\\|")); // 按竖线拆分 } } // 注册Converter @Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addFormatters(FormatterRegistry registry) { registry.addConverter(new CustomListConverter()); } } // 控制器直接使用 @GetMapping("/posts/filter") public List<Post> filterPosts( @RequestParam("tags") List<String> tags // 自动应用Converter ) { // 处理逻辑 } ``` --- ### 关键注意事项 1. **空值处理** ```java @RequestParam(required = false) List<String> tags // 允许空列表 ``` 2. **参数校验** ```java @GetMapping("/search") public ResponseEntity<?> search( @RequestParam("keywords") @Size(min = 1, max = 5, message = "关键词数量1-5个") List<String> keywords ) { // 自动触发参数校验 } ``` 3. **URL 编码问题** 默认自动解码,如需保留原始值: ```java @RequestParam(value = "q", required = false) @Encoded String rawQuery // 需自定义处理 ``` 4. **Swagger 文档支持** 添加 `@Parameter` 注解明确参数类型: ```java @RequestParam("tags") @Parameter(description = "标签列表", schema = @Schema(type = "array")) List<String> tags ``` --- ### 完整实战示例 ```java // 接收多类型参数的控制器 @RestController @RequestMapping("/api") public class PostController { // 场景1:接收同名参数列表 @GetMapping("/posts") public List<Post> getPostsByTags( @RequestParam("tags") List<String> tags, @RequestParam(defaultValue = "1") int page ) { return postService.findByTags(tags, page); } // 场景2:接收逗号分隔参数(需配置Converter) @GetMapping("/search") public List<Post> searchPosts( @RequestParam("keywords") List<String> keywords ) { return postService.search(keywords); } } // 配置类 @Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addFormatters(FormatterRegistry registry) { // 注册字符串到List的转换器 registry.addConverter(new Converter<String, List<String>>() { @Override public List<String> convert(String source) { return Arrays.asList(source.split(",")); } }); } } ``` 根据前端传递参数的具体格式,选择对应的接收策略即可实现无缝对接。推荐优先使用 `@RequestParam List<String>` 方案,与 Retrofit 的默认传参方式完美兼容。
评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值