In the Spring Boot ecosystem, the annotations changed a great deal between Swagger 2.0 (typically using the Springfox dependency) and Swagger 3.0 (typically using the Springdoc-openapi dependency, based on the OpenAPI 3 spec).

Below is a complete correspondence table of the common annotations in Swagger 2.0 vs. Swagger 3.0 (OpenAPI 3):

1. Core annotation correspondence table

Description Swagger 2.0 annotation (io.swagger.annotations) Swagger 3.0 annotation (io.swagger.v3.oas.annotations) Notes
Mark a controller class @Api(tags = "User API") @Tag(name = "User API") 3.0 removed the description attribute; use name uniformly
Mark an API method @ApiOperation(value = "Get user") @Operation(summary = "Get user") In 3.0 value became summary
Request/entity class @ApiModel(value = "User object") @Schema(description = "User object") 3.0 greatly simplified this; use @Schema uniformly
Entity class property @ApiModelProperty(value = "Name") @Schema(description = "Name") As above, merged into @Schema
Ignore a property @ApiModelProperty(hidden = true) @Schema(hidden = true)
Ignore a whole class/method @ApiIgnore @Hidden For endpoints or parameters you don’t want exposed in docs

2. Request-parameter annotation correspondence table

For method parameters (URL path parameters, query parameters, etc.), 3.0 introduced a more structured configuration:

Description Swagger 2.0 annotation Swagger 3.0 annotation
A single container parameter @ApiImplicitParam @Parameter
Multiple container parameters @ApiImplicitParams({ ... }) @Parameters({ ... })
A regular method parameter @ApiParam(value = "User ID") @Parameter(description = "User ID")

💡 Note (change in how @Parameter is used): In 3.0, for a path parameter (@PathVariable) or query parameter (@RequestParam), you can put @Parameter directly before the parameter:

// Swagger 3.0 example
@GetMapping("/{id}")
public User getUser(@Parameter(description = "User ID", example = "1") @PathVariable Long id)

3. Response-status-code annotation correspondence table

Description Swagger 2.0 annotation Swagger 3.0 annotation
A single common response @ApiResponse(code = 404, message = "Not Found") @ApiResponse(responseCode = "404", description = "Not Found")
Multiple common responses @ApiResponses({ ... }) @ApiResponses({ ... }) (name unchanged, internal components changed)

4. Dependency migration comparison (supplement)

Besides the annotation package path changing from io.swagger.annotations.* to io.swagger.v3.oas.annotations.*, if you’re doing a project upgrade, the Maven dependencies also need to be updated in sync:

  • Swagger 2.x (Springfox):
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.x.x</version>
</dependency>
  • Swagger 3.x (Springdoc):
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>3.x.x (for Spring Boot 3)</version>
</dependency>