Introduction

@RequestParam is how Spring MVC maps query-string values and form parameters into controller method arguments. Swagger UI, or more precisely the OpenAPI description behind it, can show those parameters cleanly if the endpoint signature is designed clearly and the documentation layer sees the metadata it needs. In practice, the integration is straightforward once you distinguish required parameters, optional parameters, and documented defaults.

Start with a Plain Spring Controller Method

A basic @RequestParam endpoint already gives Swagger UI enough structure to render an input field.

1import org.springframework.web.bind.annotation.GetMapping;
2import org.springframework.web.bind.annotation.RequestParam;
3import org.springframework.web.bind.annotation.RestController;
4
5@RestController
6public class GreetingController {
7
8    @GetMapping("/greet")
9    public String greet(@RequestParam String name) {
10        return "Hello, " + name;
11    }
12}

In Swagger UI, this usually appears as a required query parameter named name. When the user clicks "Try it out," the request becomes /greet?name=....

Make Optional Parameters Explicit

If a parameter is optional, say so in the controller signature. Otherwise both Spring and the OpenAPI layer treat it as required by default.

1import org.springframework.web.bind.annotation.GetMapping;
2import org.springframework.web.bind.annotation.RequestParam;
3import org.springframework.web.bind.annotation.RestController;
4
5@RestController
6public class SearchController {
7
8    @GetMapping("/search")
9    public String search(
10        @RequestParam String query,
11        @RequestParam(required = false) Integer limit
12    ) {
13        return "query=" + query + ", limit=" + limit;
14    }
15}

This communicates the API contract more clearly both to Spring and to Swagger UI.

If you want a default, express it directly:

1@GetMapping("/search")
2public String search(
3    @RequestParam String query,
4    @RequestParam(defaultValue = "10") int limit
5) {
6    return "query=" + query + ", limit=" + limit;
7}

A documented default is often better than a nullable wrapper type if the endpoint has an obvious fallback behavior.

Add Explicit OpenAPI Metadata When Needed

Modern Spring projects commonly use springdoc-openapi to generate the OpenAPI description that Swagger UI renders. If the generated parameter details are too bare, add @Parameter metadata.

1import io.swagger.v3.oas.annotations.Parameter;
2import org.springframework.web.bind.annotation.GetMapping;
3import org.springframework.web.bind.annotation.RequestParam;
4import org.springframework.web.bind.annotation.RestController;
5
6@RestController
7public class ReportController {
8
9    @GetMapping("/reports")
10    public String reports(
11        @Parameter(description = "Report category")
12        @RequestParam String type,
13
14        @Parameter(description = "Maximum number of rows to return")
15        @RequestParam(defaultValue = "50") int limit
16    ) {
17        return "type=" + type + ", limit=" + limit;
18    }
19}

That makes Swagger UI more informative without changing the runtime behavior of the endpoint.

Know What Swagger UI Is Actually Reading

Swagger UI itself does not inspect your controller code directly. It reads an OpenAPI document produced by your documentation tooling. That means if parameters are missing or incorrectly marked, the real debugging target is often the generated OpenAPI description or the documentation library configuration, not the UI layer itself.

The flow is:

1. Spring controller defines request handling.
2. OpenAPI generator inspects annotations and signatures.
3. Swagger UI renders the generated document.

That mental model helps when the request works at runtime but the documentation looks wrong.

Choose Parameter Types Deliberately

@RequestParam is a good fit for:

1. Filters
2. Pagination controls
3. Sorting options
4. Simple flags

It is not a good fit for large structured payloads that belong in a request body. If Swagger UI becomes cluttered because the endpoint has too many query parameters, that is often a sign the API contract itself should be reconsidered.

Test Both Runtime and Documentation

When validating the endpoint, check two things separately:

1. The controller handles requests correctly.
2. Swagger UI renders the parameter contract correctly.

For example:

curl "http://localhost:8080/search?query=spring&limit=5"

If the endpoint works but Swagger UI is missing metadata, inspect the OpenAPI generator configuration. If Swagger UI looks right but the runtime behavior is wrong, inspect the Spring controller signature and binding rules.

Common Pitfalls

• Leaving an optional parameter as required in the controller signature and then wondering why Swagger UI marks it mandatory.
• Using @RequestParam for data that should really be modeled as a request body.
• Assuming Swagger UI reads Spring annotations directly instead of through generated OpenAPI metadata.
• Forgetting to document defaults and descriptions when the raw parameter name is not self-explanatory.
• Debugging the UI first when the actual problem is a mismatch between controller design and generated OpenAPI output.

Summary

• '@RequestParam maps query-string or form parameters into Spring controller method arguments.'
• Required, optional, and defaulted parameters should be modeled explicitly in the method signature.
• Swagger UI reflects the OpenAPI document generated from those signatures and annotations.
• Add @Parameter metadata when the generated documentation needs clearer descriptions.
• Validate both the runtime behavior and the generated documentation instead of assuming one proves the other.