Transitioning Swagger 1.5 to 2.0 annotations
Transitioning Swagger annotations from version 1.5 to 2.0 can be a chore, as a lot changed with Swagger falling under the banner of the Open API Initiative. I wrote some RegExes that I found helpful for transitioning the annotations, and I hope they’re useful for you as well.
Remove @Api
In annotations 1.5, the @Api annotation was used at the class level to apply Swagger definitions to the operations. This is no longer the case. So, to update to annotations 2.0, remove all instances of @Api.
Transition @ApiOperation to @Operation
First, replace all instances of @ApiOperation with @Operation. Additionally, remove @ApiResponses annotations, as these are no longer used.
Then, run the following search-and-replace RegExes:
| Search | Replace |
|---|---|
(@Operation\([\s\S]*?)\bvalue\b |
$1summary |
(@Operation\([\s\S]*?)\bnotes\b |
$1description |
(@Operation\([\s\S]*?)\bresponse\b[\s]*?\=[\s]*?(\b[a-zA-Z.]+.class) |
$1responses = {@ApiResponse(content = @Content(schema = @Schema(implementation = $2)))} |
Optionally, tag your operations with:
| Search | Replace |
|---|---|
(@Operation\() |
$1tags = { "Your" "tags" "here" } |
For reference, here’s an example of the @Operation annotation in action.
@Operation(summary = "Finds Pets by status",
description = "Multiple status values can be provided with comma seperated strings",
responses = {
@ApiResponse(
content = @Content(mediaType = "application/json",
schema = @Schema(implementation = Pet.class))),
@ApiResponse(
responseCode = "400", description = "Invalid status value"
)
}
)
Transition @ApiParam to @Parameter
First, replace all instances of @ApiParam with @Parameter.
Then, run the following search-and-replace RegExes:
| Search | Replace |
|---|---|
(@Parameter\([\s\S]*?)\bvalue\b |
$1description |
One caveat to this: @Parameter is not applicable for use in a non-resource class (e.g. a data model). In cases like this, use @Schema instead.
Transition @ApiModelProperty to @Schema
First, replace all instances of @ApiModelProperty and @ApiModel with @Schema.
Then, run the following search-and-replace RegExes:
| Search | Replace |
|---|---|
(@Schema\([\s\S]*?)\bvalue\b |
$1description |
Comments