Hey there! I’ve dealt with this exact frustration with SpringFox before—when you pass a complex object as a request parameter, Swagger UI defaults to splitting it into all its nested fields, which totally breaks your custom converter flow. Let’s get this sorted out for you.

Why This Happens #

SpringFox automatically introspects your Filter class and tries to expose every nested field as a separate query parameter. Since your Sort class has propertyName and order fields, it’s rendering those instead of recognizing you want a single sort parameter that accepts your custom string format (like +firstName).

Solution 1: Manually Define Parameters with @ApiImplicitParams #

The quickest fix is to explicitly tell Swagger UI what parameters to display, overriding the automatic introspection. Add these annotations to your controller method:

@GetMapping("/users")
@ApiImplicitParams({
    @ApiImplicitParam(
        name = "page",
        value = "Page number (starting from 1)",
        dataType = "integer",
        paramType = "query",
        example = "1"
    ),
    @ApiImplicitParam(
        name = "size",
        value = "Number of records per page",
        dataType = "integer",
        paramType = "query",
        example = "10"
    ),
    @ApiImplicitParam(
        name = "sort",
        value = "Sort format: Use +propertyName for ascending, -propertyName for descending",
        dataType = "string",
        paramType = "query",
        example = "+firstName"
    )
})
public ResponseEntity<UserDto> getUsers(Filter filter) {
    return ResponseEntity.ok(userService.findUsers(filter));
}

This will force Swagger UI to show three clean query parameters, matching your desired URL format. Your existing String-to-Sort converter will still work behind the scenes—this just fixes the UI display.

Solution 2: Create a Custom SpringFox Plugin (For Reuse) #

If you use Sort across multiple endpoints, a reusable plugin is better. This tells SpringFox to always render Sort parameters as a single string query parameter instead of splitting them.

Create a plugin class:

@Component
public class SortParameterSwaggerPlugin implements ParameterBuilderPlugin {

    @Override
    public void apply(ParameterContext context) {
        ResolvedMethodParameter methodParam = context.resolvedMethodParameter();
        // Check if the parameter type is our Sort class
        if (Sort.class.equals(methodParam.getParameterType().getErasedType())) {
            context.parameterBuilder()
                    .name("sort")
                    .modelRef(new ModelRef("string"))
                    .parameterType("query")
                    .description("Sort format: +propertyName (ascending) or -propertyName (descending)")
                    .example("+firstName");
        }
    }

    @Override
    public boolean supports(DocumentationType documentationType) {
        // Only apply to Swagger 2
        return DocumentationType.SWAGGER_2.equals(documentationType);
    }
}

Make sure this class is scanned by Spring (either via @ComponentScan or placing it in your application’s base package). Now any endpoint that uses Sort (directly or nested in another object like Filter) will display the correct single parameter in Swagger UI.

Bonus: Hide Nested Fields (If Needed) #

If you still see the nested sort.propertyName and sort.order parameters popping up, add @ApiIgnore to the sort field in your Filter class:

public class Filter {
    private Integer page;
    private Integer size;
    
    @ApiIgnore
    private Sort sort;

    // Getters and setters
}

This tells SpringFox to ignore the nested field entirely, so it won’t generate those extra parameters.

Either solution should fix your parameter display issue while keeping your custom converter working as expected.

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