Upgrading Swagger 2 to Swagger 3 (OpenAPI 3) – Everything You Need to Know

A lot of APIs are documented using Swagger, it’s a good thing that APIs are documented. This helps developers and users to make it easy to understand the request and response.

Earlier APIs were documented using Swagger 2. Now that OpenAPI has been released (since 2017, the actual version is 3.1 and has been available since February 15, 2021), some projects haven’t updated their documentation tools. I will try to help you do so in this article.

Migrating from Swagger 2 to Swagger 3 (OpenAPI 3) in a Java project involves updating your dependencies, configuration, and potentially your code. Here are the general steps you can follow:

1. Update Dependencies:

• Make sure to use the latest Swagger library version that supports OpenAPI 3. Update your Maven or Gradle dependencies accordingly.

Maven:

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.1.10</version> <!-- Update to the latest version -->
</dependency>

Gradle:

implementation 'io.swagger.core.v3:swagger-annotations:2.1.10' // Update to the latest version

2. Update Swagger Configuration:

• If you’re using a Swagger configuration file (e.g., swagger-config), update it to use OpenAPI 3 syntax.

Example Configuration:

Yaml

openapi: 3.0.0
info:
  title: Your API Title
  version: 1.0.0

3. Update Swagger Annotations:

• Replace Swagger 2 annotations in your Java code with equivalent OpenAPI 3 annotations.

Example:

@ApiOperation(value = "Get user by ID", response = User.class)
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "Success", response = User.class),
    @ApiResponse(code = 404, message = "User not found")
})
@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    // Implementation
}

// OpenAPI 3
@Operation(summary = "Get user by ID", responses = {
    @ApiResponse(responseCode = "200", description = "Success", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))),
    @ApiResponse(responseCode = "404", description = "User not found")
})
@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    // Implementation
}

Swagger 2 to Swagger 3 annotations

Swagger 3 is an updated version of Swagger 2 and has some changes in annotations. This will help to understand the updated annotations to be updated.

• @Api → @Tag
• @ApiIgnore → @Parameter (hidden = true) or @Operation (hidden = true) or @Hidden
• @ApiImplicitParam → @Parameter
• @ApiImplicitParams → @Parameters
• @ApiModel → @Schema
• @ApiModelProperty(hidden = true) → @Schema (accessMode = READ_ONLY)
• @ApiModelProperty → @Schema
• @ApiOperation(value = “foo”, notes = “bar”) → @Operation (summary = “foo”, description = “bar”)
• @ApiParam → @Parameter
• @ApiResponse(code = 404, message = “foo”) → @ApiResponse(responseCode = “404”, description = “foo”)ApiResponse(responseCode = “404”, description = “foo”)

4. Update Swagger UI Configuration (if used):

• If you use Swagger UI to visualize your API documentation, ensure it is compatible with OpenAPI 3.

5. Testing:

• Test your API thoroughly to ensure that it works as expected with the updated Swagger annotations and configuration.

6. Documentation:

• Update your API documentation to reflect the changes introduced by OpenAPI 3.

7. Tools:

• If you use code generation tools based on Swagger, ensure that they support OpenAPI 3 and regenerate any necessary code.

Example Swagger 3 Annotations:

Here’s an example using Swagger 3 annotations:

@Operation(summary = "Get user by ID", responses = {@ApiResponse(responseCode = "200", description = "Success", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))),
    @ApiResponse(responseCode = "404", description = "User not found")
})
@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    // Implementation
}

Remember that this is a general guideline, and you may need to adapt it based on your specific use case and the features you’re using in your Swagger 2 documentation. Always refer to the official documentation for the latest information and updates.