Springdoc and OpenAPI (Annotation Usage Guide)

QueryString Processing Methods Comparison

#

Let’s compare two methods for handling QueryString in Spring.

Method 1: Receiving as Object (ParameterObject)

#

@Operation(tags = {"swagger"})
@GetMapping("/hello/parameters1")
public ResponseEntity<List<ResponseTest>> parameterObjectTest(ParameterObjectReq req) {
    ResponseTest response = new ResponseTest(req.email(), req.password(), req.occupation());
    return ResponseEntity.ok(List.of(response));
}

Method 2: Receiving as Individual Parameters (@RequestParam)

#

@Operation(tags = {"swagger"})
@GetMapping("/hello/parameters2")
public ResponseEntity<List<ResponseTest>> parameterObjectTest2(
        @RequestParam(value = "email") String email,
        @RequestParam(value = "pw") String password,
        @RequestParam(value = "oq") OccupationStatus status
) {
    ResponseTest response = new ResponseTest(email, password, status);
    return ResponseEntity.ok(List.of(response));
}

Model Definition

#

ParameterObjectReq (Request DTO)

public record ParameterObjectReq(
        String email,
        String password,
        OccupationStatus occupation
) {
}

OccupationStatus (Enum)

public enum OccupationStatus {
    STUDENT,
    EMPLOYEE,
    UNEMPLOYED
}

Differences Between the Two Approaches

#

While @RequestParam is commonly used for receiving QueryString requests, when there are many parameters, you can receive the QueryString as an Object like in the first method.

@RequestParam vs ParameterObject

#

• @RequestParam: By default set to required = true, making request values mandatory.
• ParameterObject: Spring automatically binds QueryString to the object’s field values without any special annotation. However, since required is not set by default, null values can be passed.

ParameterObject vs @RequestParam Conversion in Springdoc

#

Using ParameterObject

#

Using @RequestParam

#

Using @ParameterObject Annotation

#

To make Springdoc convert ParameterObject like when using @RequestParam and display the Required status, configure as follows.

Code Example

#

@ParameterObject
public record ParameterObjectReq(
        @NotNull
        String email,

        @NotNull
        String password,

        OccupationStatus occupation
) {
}

@ParameterObject is a Springdoc annotation. When receiving multiple QueryStrings as an Object, specifying it on the class will make it recognize and convert like @RequestParam.

JSR-303 Support

#

Springdoc supports JSR-303 and allows the following validation annotations:

• @NotNull
• @Min, @Max
• @Size
• Other validation annotations

According to Springdoc official documentation

This library supports

• OpenAPI 3
• Spring-boot (v1, v2 and v3)
• JSR-303, specifically for @NotNull, @Min, @Max, and @Size
• Swagger-ui
• OAuth 2
• GraalVM native images

Conversion Result

#

The spec file is written so that ParameterObject is also recognized as @RequestParam, and occupation without @NotNull is displayed as optional in the Required field.

Left Image: When @ParameterObject is specified, Springdoc recognizes it and converts to proper spec

Swagger2 → Swagger3 Annotations

#

• When using an object to capture multiple request query params, use the @ParameterObject annotation on that method argument
• This step is optional: Replace with GroupedOpenApi bean only if you have multiple Docket beans

Using @Tag Annotation

#

The @Tag annotation enables the following grouping:

• Grouping by Controller
• Grouping by method within Controller
• Grouping in spec file conversion according to the name specified in @Tag
• File creation with that name when generating client code using OpenAPI Generator

Cautions When Using Multiple @Tag

#

Question: What happens if you group with @Tag at the top level and set a different tag name in the @Operation of a lower-level method?

Test Result

#

When @Tag(name = "swagger") is set at the top level and tags = {"swagger123"} is added in the @Operation of the postHello method, the same endpoint is created as duplicate groups.

Problem

#

Using OpenAPI Generator in this state causes the problem of duplicate client code being generated as shown below.

Recommendation: Unless there’s a special case, it’s recommended to use @Tag grouping only at the Controller’s top level.

File Naming for OpenAPI Generator Client Code Generation

#

When generating client code, the name specified in @Tag + -api is added as a postfix. To customize this, you need to modify the Mustache file.

References

#

• Using Templates | OpenAPI Generator
• Mustache.js GitHub
• OpenAPI Generator Usage Guide
• Auto-generating Safe Models and Standardized Implementation Code with OpenAPI Generator

Authentication-Related OpenAPI Specs

#

OpenAPI supports various authentication methods. Key configuration items are as follows.

type (Authentication Format)

#

Currently supports API Key, HTTP, OAuth2, and OpenID Connect methods. Note: OpenAPI v2 spec does not support OpenID Connect method.

Supported Types

• http: Basic, Bearer and other HTTP authentication schemes
• apiKey: API key and cookie authentication
• oauth2: OAuth2 authentication
• openIdConnect: OpenID Connect discovery

Key Configuration Items

#

• name: Authentication key name (required when using API Key method)
• in: Specifies authentication key location (choose from query, header, cookie, required when using API Key method)
• scheme: Specifies authentication method (Basic or Bearer, required when using HTTP authentication)
• bearerFormat: Bearer token format (commonly JWT)
• flows: OAuth2 flow type (choose from implicit, password, clientCredentials, authorizationCode)
• openIdConnectUrl: OpenID Connect URL (recommended to use OAuth2 or Bearer token method as alternative in OpenAPI v2 spec)

@Deprecated Strategy

#

When there are changes to DTO specs due to API version updates, use the following phased strategy.

Phase 1: Mark with @Deprecated

#

First, add the @Deprecated annotation to the field that will change.

public class UserDto {
    @Deprecated
    private String oldField;

    private String newField;
}

The OpenAPI spec will also show deprecated for that schema field, and when generating code on the frontend, the field will be marked as deprecated. This notifies the frontend team in advance that the field will be removed soon.

Phase 2: Apply @Schema(hidden = true)

#

Once the frontend has completed migration to the new spec, add @Schema(hidden = true) to the @Deprecated field on the server so that the field is no longer generated in the OpenAPI spec.

public class UserDto {
    @Deprecated
    @Schema(hidden = true)
    private String oldField;  // Excluded from spec

    private String newField;
}

Phase 3: Remove Field

#

After sufficient time has passed, completely remove the field.

This phased approach enables safe API version management between frontend and backend.