如何在Swagger UI中自定义端点参数的顺序

这个问题我之前也碰到过，Spring默认按参数名字母排序确实不太灵活，想要把fromLocation放到最后，有几个实用的方案可以解决：

方案1：用Swagger的@ApiParam指定顺序（Springfox版本） #

如果你项目里用的是Springfox的Swagger，直接在参数上添加@ApiParam注解并设置order属性就行——数值越大，参数在列表里越靠后。给其他参数设较小的order值，把fromLocation的order设成最大的（比如99），就能让它排到最后。

示例代码：

@GetMapping("/your-target-endpoint")
public ResponseEntity<?> handleRequest(
    @ApiParam(order = 1) String destination,
    @ApiParam(order = 2) Integer pageSize,
    @ApiParam(order = 99) String fromLocation
) {
    // 你的业务逻辑
    return ResponseEntity.ok().build();
}

方案2：用SpringDoc的@Parameter指定顺序（替代Springfox的新版本） #

如果是用SpringDoc（现在更推荐的Swagger替代方案），就换成@Parameter注解，逻辑和上面完全一样，通过order属性控制顺序：

示例代码：

@GetMapping("/your-target-endpoint")
public ResponseEntity<?> handleRequest(
    @Parameter(order = 1) String destination,
    @Parameter(order = 2) Integer pageSize,
    @Parameter(order = 99) String fromLocation
) {
    // 你的业务逻辑
    return ResponseEntity.ok().build();
}

方案3：封装成DTO类（和@ApiModel风格一致） #

如果你想和@ApiModel的用法统一，最稳妥的方式是把所有参数封装成一个DTO类，然后在DTO的字段上用@ApiModelProperty指定order属性，最后控制器方法直接接收这个DTO作为参数。这样不仅能自定义顺序，还能让参数结构更清晰。

示例DTO类：

@ApiModel(description = "请求参数DTO")
public class RequestParamsDTO {
    @ApiModelProperty(order = 1, value = "目标地址")
    private String destination;
    
    @ApiModelProperty(order = 2, value = "每页数量")
    private Integer pageSize;
    
    @ApiModelProperty(order = 99, value = "来源地址")
    private String fromLocation;

    // 省略getter、setter
}

控制器方法：

@GetMapping("/your-target-endpoint")
public ResponseEntity<?> handleRequest(RequestParamsDTO params) {
    // 你的业务逻辑
    return ResponseEntity.ok().build();
}

补充说明 #

Spring MVC原生的参数列表默认是按参数名的字母顺序排序的，如果只是单纯调整接口文档里的顺序，用前两个方案就行；如果想同时调整请求绑定和文档的参数顺序，封装DTO的方式更彻底。

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