Swagger2中@ApiParam的type属性不生效，如何修改契约参数类型？

我之前也碰到过一模一样的问题！其实核心原因是：Swagger（尤其是Springfox实现的版本）在解析方法参数类型时，会优先读取Java方法参数的实际类型，而@ApiParam的type属性在这里并不会覆盖这个自动推断的结果——这就是为什么你设置了type = "java.lang.String"，但swagger-ui里还是显示Integer类型的原因。

下面给你几个可行的解决方案，根据你的业务场景选就行：

方案1：直接修改参数类型（推荐，最直观） #

如果业务允许，可以把方法参数的类型改成String，然后在方法内部自己转换成Integer使用。这样Swagger会自动识别String类型，同时不影响后端逻辑：

ResponseEntity<Void> delete(
    @ApiParam(value = "The id of the object", required = true) 
    String id // 直接改成String类型
) {
    // 内部转换为Integer，按需处理异常
    Integer idInt = Integer.parseInt(id);
    // 执行你的删除逻辑...
    return ResponseEntity.ok().build();
}

方案2：用@ApiImplicitParam 覆盖类型 #

如果你不想修改参数的实际Java类型，可以用@ApiImplicitParam注解来明确指定参数的显示类型，这个注解的优先级高于方法参数的实际类型。注意要配合@ApiImplicitParams包裹（哪怕只有一个参数）：

@ApiImplicitParams({
    @ApiImplicitParam(
        name = "id", // 要和方法参数名一致
        value = "The id of the object",
        required = true,
        dataType = "string", // 指定显示为string类型
        paramType = "query" // 如果是路径参数就写"path"
    )
})
ResponseEntity<Void> delete(Integer id) {
    // 业务逻辑...
    return ResponseEntity.ok().build();
}

方案3：路径参数的特殊处理 #

如果这个id是@PathVariable路径参数，只需要把上面的paramType改成"path"即可：

@ApiImplicitParams({
    @ApiImplicitParam(
        name = "id",
        value = "The id of the object",
        required = true,
        dataType = "string",
        paramType = "path"
    )
})
@DeleteMapping("/objects/{id}")
ResponseEntity<Void> delete(@PathVariable Integer id) {
    // 业务逻辑...
    return ResponseEntity.ok().build();
}

另外补充一句：如果你的项目用的是Springfox 3.x及以上版本，确保你的Swagger配置类已经正确开启了API扫描，不过这不是导致类型不生效的核心原因，核心还是上面说的类型推断优先级问题。

内容的提问来源于stack exchange，提问作者renke