REST Expanders 3.10.0
Some bugfixes were applied, use version 3.10.3
instead of 3.10.0
.
Changes and improvements
OpenApi 3.0 support
Using OpenApi 3.0 requires at least version 2.15.2
of the Docker image nsx-tomee-base
.
In this version of rest-expanders, we've introduced support for OpenAPI 3.0. Previously we only supported OpenAPI 2.0, which was Swagger originally. Due to some technical challenges, we were not able to support OpenAPI 3.0 up to this point. Now that these hurdles have been cleared, we've finished the implementation and made it the new default.
The new version of the specification is also integrated with a Swagger UI front-end as was the case with the previous specification. This version does rely on a new major version of the Swagger library, which brings many breaking changes. As a regular, custom code will be heavily impacted by this change. We do provide a model option to switch back to OpenAPI 2.
For OpenAPI 3.0, the endpoints for the api specification have changed:
/{applicationName}/{basePath}/swagger.json
to/{applicationName}/{basePath}/openapi.json
/{applicationName}/{basePath}/swagger.yaml
to/{applicationName}/{basePath}/openapi.yaml
The location of Swagger UI has not been altered.
More information about updating can be found in the migration guide.
SecurityRight annotation
The SecurityRight
annotation is used to define rights for an endpoint. Previously these would only be added to
expanded endpoints when use of account::DataAccess
was enabled. This made it difficult to add more functionality to
the annotation. Now this annotation is added to all expanded endpoints and anchors are available in the annotation to
add additional property values.
Migration guide
Updating from Swagger 1.x to Swagger 2.x
Version 2 of the Swagger library, which support OpenAPI 3.x, is a complete rework of the entire library. We use annotations to provide information about the API in the codebase, which will all have to be replaced in any custom code that may use them.
Unfortunately there is no official migration guide. But we will provide some side-by-side comparisons of expanded code that make use of the annotations. For custom code that goes beyond the scope of these examples, please refer to the documentation of Swagger 2.x on how to use the new annotations.
The option jaxrs.openapi.version: 2
on the Application can be used to revert back to OpenAPI 2.x if upgrading is not
immediately possible.
Connectors
In Swagger 1.x we group the endpoints of a connector by applying a tag in the tags
property of the @Api
annotation
on the connector class. This annotation was removed in Swagger 2.x and can now be replaced with one or more @Tag
annotations.
@Api(tags = { "AccountRequest Apis" })
@Tag(name = "AccountRequest Apis")
Endpoints
In Swagger 1.x, endpoints are described by two annotations on the method. The @ApiOperation
was used to describe the
endpoint itself, where we used the value
property for the description. In Swagger 2.x, this annotation was replaced
by the @Operation
annotation with the summary
property for the description.
Though there is still an @ApiResponses
in Swagger 2.x, we've moved the @ApiReponse
annotations to the reponses
property in the @Operation
annotation, so all annotations are grouped together.
@ApiResponse
itself has also been changed considerably. The code
property has been changed responseCode
and a
string value. The message
property is now description
and the response
is now described by @Content
in the
content
field.
@ApiOperation(
value = "Retrieve all AccountRequest objects"
)
@ApiResponses(value = {
@ApiResponse(code = 400, message = "Bad request", response = RestErrorResponse.class),
@ApiResponse(code = 401, message = "Access denied", response = RestErrorResponse.class),
@ApiResponse(code = 404, message = "Not found", response = RestErrorResponse.class),
@ApiResponse(code = 500, message = "Internal server error", response = RestErrorResponse.class),
})
@Operation(
summary = "Retrieve all AccountRequest objects",
responses = {
@ApiResponse(responseCode = "400", description = "Bad request", content = @Content(
mediaType = "application/json", schema = @Schema(implementation = RestErrorResponse.class))),
@ApiResponse(responseCode = "401", description = "Access denied", content = @Content(
mediaType = "application/json", schema = @Schema(implementation = RestErrorResponse.class))),
@ApiResponse(responseCode = "404", description = "Not found", content = @Content(
mediaType = "application/json", schema = @Schema(implementation = RestErrorResponse.class))),
@ApiResponse(responseCode = "500", description = "Internal server error", content = @Content(
mediaType = "application/json", schema = @Schema(implementation = RestErrorResponse.class))),
}
)
Parameters
In Swagger 1.x, the @ApiParam
parameter was used to identify the parameter that represents the body of a request.
This was replaced in Swagger 2.x by @RequestBody
.
@ApiParam CityPostInputModel inputModel
@RequestBody(required = true) CityPostInputModel inputModel
For any other parameter, the @ApiParam
parameter was replaced with @Parameter
. Some fields were moved to a @Schema
object:
@ApiParam(allowableValues={"a", "b", "c"})
@Parameter(schema = @Schema(allowableValues={"a", "b", "c"}))
Model fields
In Swagger 1.x, the @ApiModelProperty
parameter was used to mark fields in payload models. These have been replaced
by the @Schema
annotation in Swagger 2.x. The value
property for the description was replaced with description
.
@ApiModelProperty(value = "The new name of the city!", dataType = "string", required = true)
private String name;
@Schema(description = "The new name of the city!", type = "string", requiredMode = Schema.RequiredMode.REQUIRED)
private String name;
Additionally, for arrays a specific @ArraySchema
annotation was introduced in Swagger 2.x that contains the @Schema
annotation for the nested type.
@ApiModelProperty(value = "Some data", dataType = "BYTE", required = true)
private byte[] data;
@ArraySchema(arraySchema = @Schema(description = "Some data", type = "byte", requiredMode = Schema.RequiredMode.REQUIRED))
private byte[] data;
In case of an integer type, you should now use the allowed types (number
or integer
) for OpenAPI 3.0 and in case
of number
, use the format property to specify the specific type:
@ApiModelProperty(dataType = "Long")
private long value;
@Schema(type = "number", format = "int64")
private long value;
Migrating SecurityRight annotation
Because the @SecurityRight
annotation was not expanded by default previously, it will be required to update any
custom code that added it to expanded endpoints, as well as expanders that added it through a feature.
// anchor:custom-post-annotations:start
@SecurityRight(disabled = true)
// anchor:custom-post-annotations:end
@SecurityRight(
// @anchor:post-securityRight:start
// @anchor:post-securityRight:end
// anchor:custom-post-securityRight:start
disabled = true
// anchor:custom-post-securityRight:end
)