Springdoc and OpenAPI (Annotation Usage Guide)

Tue, 17 Oct 2023 17:12:52 +0900

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

Swagger2	Swagger3	Description
@Api	@Tag	Displays swagger resource at class level (for grouping) `name` : Tag name `description` : Tag description
@ApiIgnore	@Parameter(hidden = true) @Operation(hidden = true) @Hidden	This annotation allows hiding parameters in swagger-ui. For requestBody or ResponseBody, use @JsonProperty(access = JsonProperty.Access.READ_ONLY)
@ApiImplicitParam	@Parameter	Configuration and resource display for single RequestParam
@ApiImplicitParams	@Parameters	Configuration for multiple RequestParams
@ApiModel	@Schema	`description` : Human-readable name `defaultValue` : Default value `allowableValues` : Allowable values (set when enumerable)
@ApiModelProperty(hidden = true)	@Schema(accessMode = READ_ONLY)
@ApiOperation(value = “foo”, notes = “bar”)	@Operation(summary = “foo”, description = “bar”)	`summary` : Brief description of API `description` : Detailed description of API `responses` : List of API responses `parameters` : List of API parameters
@ApiParam	@Parameter	`name` : Parameter name `description` : Parameter description `in` : Parameter location (query, header, path, cookie)
@ApiResponse(code = 404, message = “foo”)	@ApiResponse(responseCode = “404”, description = “foo”)	`responseCode` : HTTP status code `description` : Response description `content` : Response payload structure `schema` : Schema used in payload `hidden` : Whether to hide schema `implementation` : Schema target class

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

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.

Mastering OpenAPI Generator

Mon, 16 Oct 2023 16:56:35 +0900

What is Swagger?

Swagger is a framework for OAS (OpenAPI Specification) that allows you to specify and manage the specifications of APIs. Through Swagger, you can design, build, and document REST API services.

Swagger Tools

Swagger provides the following key tools

Swagger UI: A tool that visualizes Swagger API specifications in HTML format for easy viewing
Swagger Codegen: A CLI tool that automatically generates client and server code based on Swagger specifications
Swagger Editor: An editor for creating API design documents and specifications according to Swagger standards

Springfox vs Springdoc

Springfox Swagger is a library that helps you easily write API documentation using Swagger in projects using Spring or Spring Boot.

When Springfox stopped updating, Springdoc emerged and rapidly gained popularity with active updates. Springdoc is also a library that supports Swagger documentation creation and is now the more recommended choice over Springfox.

Swagger Codegen vs OpenAPI Generator

Swagger is a trademark of SmartBear, and Swagger Codegen is a project included within it.

OpenAPI Generator is a community-driven open-source project that started as a fork of the Swagger Codegen project. Currently, more than 40 top project contributors and founding members of Swagger Codegen are participating together.

OpenAPI Generator License

OpenAPI Generator follows Apache License 2.0.

What is Apache License 2.0?

Apache License 2.0 grants the following rights

Anyone can create programs derived from the software
Copyright can be transferred and transmitted
Parts or the whole can be used for personal or commercial purposes
When redistributing, you don’t necessarily have to include the original or modified source code
However, you must include the Apache License version and notice (clearly indicating that the software was developed under Apache License)

Background of OpenAPI Generator’s Birth

The official Q&A of OpenAPI Generator reveals the background of the project’s creation

Difference in Version Philosophy The founding members of Swagger Codegen felt that Swagger Codegen 3.0.0 was too different from the 2.x philosophy. They were concerned that the overhead of maintaining two separate branches (2.x, 3.x) could cause problems similar to those experienced by the Python community.
Faster Release Cycle The founding members wanted a faster release cycle so users wouldn’t have to wait months to use the stable release version they wanted.
- Weekly patch releases
- Monthly minor releases
Community-Driven Development Proceeding as a community-driven open-source project ensures innovation, reliability, and a roadmap owned by the community.

For these reasons, the OpenAPI Generator project was born. OpenAPI Generator feels somewhat like the relationship between MySQL and MariaDB.

Migrating from Swagger Codegen

According to the official documentation, if you’re currently using Swagger Codegen 2.x version, you can conveniently migrate to OpenAPI Generator. This is because OpenAPI Generator is based on Swagger Codegen 2.4.0-SNAPSHOT version.

For detailed migration instructions, refer to the official guide

Migrating from Swagger Codegen | OpenAPI Generator

Swagger on 0AndWild_log

Springdoc and OpenAPI (Annotation Usage Guide)

QueryString Processing Methods Comparison

Method 1: Receiving as Object (ParameterObject)

Method 2: Receiving as Individual Parameters (@RequestParam)

Model Definition

Differences Between the Two Approaches

@RequestParam vs ParameterObject

ParameterObject vs @RequestParam Conversion in Springdoc

Using ParameterObject

Using @RequestParam

Using @ParameterObject Annotation

Code Example

JSR-303 Support

Conversion Result

Swagger2 → Swagger3 Annotations

Using @Tag Annotation

Cautions When Using Multiple @Tag

Test Result

Problem

File Naming for OpenAPI Generator Client Code Generation

References

Authentication-Related OpenAPI Specs

type (Authentication Format)

Key Configuration Items

@Deprecated Strategy

Phase 1: Mark with @Deprecated

Phase 2: Apply @Schema(hidden = true)

Phase 3: Remove Field

Mastering OpenAPI Generator

What is Swagger?

Swagger Tools

Springfox vs Springdoc

Swagger Codegen vs OpenAPI Generator

OpenAPI Generator License

What is Apache License 2.0?

Background of OpenAPI Generator’s Birth

Migrating from Swagger Codegen

References