REST Expanders 3.10.0

danger

Some bugfixes were applied, use version 3.10.3 instead of 3.10.0.

Changes and improvements

OpenApi 3.0 support

caution

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.

info

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.

Swagger 1.x

@Api(tags = { "AccountRequest Apis" })

Swagger 2.x

@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.

Swagger 1.x

@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),
})

Swagger 2.x

  @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.

Swagger 1.x

@ApiParam CityPostInputModel inputModel

Swagger 2.x

@RequestBody(required = true) CityPostInputModel inputModel

For any other parameter, the @ApiParam parameter was replaced with @Parameter. Some fields were moved to a @Schema object:

Swagger 1.x

@ApiParam(allowableValues={"a", "b", "c"})

Swagger 2.x

@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.

Swagger 1.x

@ApiModelProperty(value = "The new name of the city!", dataType = "string", required = true)
private String name;

Swagger 2.x

@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.

Swagger 1.x

@ApiModelProperty(value = "Some data", dataType = "BYTE", required = true)
private byte[] data;

Swagger 2.x

@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:

Swagger 1.x

@ApiModelProperty(dataType = "Long")
private long value;

Swagger 2.x

@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.

Before

// anchor:custom-post-annotations:start
@SecurityRight(disabled = true)
// anchor:custom-post-annotations:end

After

@SecurityRight(
  // @anchor:post-securityRight:start
  // @anchor:post-securityRight:end
  // anchor:custom-post-securityRight:start
  disabled = true
  // anchor:custom-post-securityRight:end
)