back to all blogsSee all blog posts

MicroProfile OpenAPI 2.0 preview plus new features and loads of improvements for Jakarta EE 9 in Open Liberty 20.0.0.11-beta

image of author
Jakub Pomykala on Sep 29, 2020
announcements , microprofile , beta , jakarta-ee ,
Post available in languages:

In 20.0.0.11-beta we have a preview of MicroProfile OpenAPI 2.0, which enables you to generate documentation directly from APIs. We have also added two new Jakarta EE 9 features, along with improvements to existing Jakarta EE 9 features, many moving up to the latest API Release Candidates.

We have two beta packages for Open Liberty:

  • All Beta Features: a new, larger package that contains all Open Liberty beta features (including Jakarta EE 9 beta features) and GA features and functions.

  • Jakarta EE 9 Beta Features: a lightweight package that contains only the Jakarta EE 9 features.

This means that you can now try out our in-development Open Liberty features by just adding the relevant coordinates to your build tools.

If you try either package, let us know what you think.

All Beta Features package

The All Beta Features package includes MicroProfile OpenAPI 2.0.

MicroProfile Logo

MicroProfile OpenAPI 2.0

MicroProfile OpenAPI 2.0 builds on top of the OpenAPI v3 specification. The OpenAPI v3 specification defines a standard, language-agnostic, interface for describing REST APIs which allows documentation to be generated from the APIs themselves. The MicroProfile OpenAPI specification provides a unified Java API for the OpenAPI v3 specification which allows Java developers to generate OpenAPI v3 documents from their JAX-RS applications. MicroProfile OpenAPI 2.0 introduces some new annotations that simplify the process of generating OpenAPI documentation for your REST APIs. It also introduces a new MicroProfile Config property prefix that can be used to define the schema for Java classes that you do not have the source code for.

@SchemaProperty

The @SchemaProperty annotation has been added to allow you to include properties in the definition of a schema when using the @Schema annotation. Previously, the @Schema annotation did not allow you to define any properties. Properties were introspected from the implementation class. With the introduction of the @SchemaProperty annotation, a list of properties can now defined using the properties attribute on the @Schema annotation, as follows:

@Schema(
    name = "User",
        description = "Telephone number to contact the user”,
        implementation = User.class,
        properties = {
            @SchemaProperty(
                name = "phone",
                description = "Telephone number to contact the user”
            )
        }
    )}

@RequestBodySchema

The @RequestBodySchema annotation has been added to provide a shorthand mechanism to specify the schema for a request body. Previously, defining the schema for a request body required the use of three different annotations, as follows:

@RequestBody(
    content = {
        @Content(
            schema = @Schema(
                implementation = MyRequestObject.class
            )
        )
    }
)

With the introduction of the @RequestBodySchema annotation, this can be simplified to the following single annotation:

@RequestBodySchema(MyRequestObject.class)

@APIResponseSchema

The @APIResponseSchema annotation has been added to provide a shorthand mechanism to specify the schema for a response body. Previously, defining the schema for a response body required the use of three different annotations, as follows:

@APIResponse(
    content = {
            @Content(
                schema = @Schema(
                    implementation = MyResponseObject.class
                )
            )
        }
    )

With the introduction of the @RequestBodySchema annotation, this can be simplified to the following single annotation:

@APIResponseSchema(MyResponseObject.class)

mp.openapi.schema.*

The mp.openapi.schema.* MicroProfile Config property prefix has been added to allow you to define the schema for Java classes using configuration rather than code. The use of this property is functionally equivalent to the use of the @Schema annotation on a Java class, but may be used in cases where you do not have access to the source code of a class. The remainder of the property key must be the fully-qualified class name and the value must be a valid OpenAPI schema object, specified in the JSON format. For example, in the case where an application needs to represent dates in epoch milliseconds, the following configuration could be used (line escapes and indentation added for readability):

mp.openapi.schema.java.util.Date = { \
   "name": "EpochMillis" \
   "type": "number", \
   "format": "int64", \
   "description": "Milliseconds since January 1, 1970, 00:00:00 GMT" \
 }

Enable OpenAPI 2.0 in the server.xml, along with any other features you’re using.

<featureManager>
    <feature>mpOpenAPI-2.0</feature>
</featureManager>

For more information:

Try it now

To try out these features, just update your build tools to pull the Open Liberty All Beta Features package instead of the main release. The beta works with Java SE 14, Java SE 11, or Java SE 8.

If you’re using Maven, here are the coordinates:

<dependency>
  <groupId>io.openliberty.beta</groupId>
  <artifactId>openliberty-runtime</artifactId>
  <version>20.0.0.11-beta</version>
  <type>pom</type>
</dependency>

Or for Gradle:

dependencies {
    libertyRuntime group: 'io.openliberty.beta', name: 'openliberty-runtime', version: '[20.0.0.11-beta,)'
}

Or take a look at our Downloads page.

Jakarta EE 9 Beta Features package

The main change you should be aware of in Jakarta EE 9 is the names of packages changing to accomodate the new jakarta.* namespace. In this Open Liberty beta, we have more Jakarta EE 9 features with their name change completed. Most features have improvements too, including many moving up to the latest API Release Candidates.

Jakarta EE Logo

This Open Liberty beta introduces the following Jakarta EE 9 features which now possess their all-new Jakarta EE 9 package names:

  • Jakarta Enterprise Beans Remote 4.0 (ejbRemote-4.0)

  • Jakarta EE Application Client 9.0 (javaeeClient-9.0) (now supports Jakarta Enterprise Beans Remote Client 4.0)

These join the Jakarta EE 9 features in previous Open Liberty betas:

  • Jakarta Authentication 2.0 (jaspic-2.0)

  • Jakarta Authorization 2.0 (jacc-2.0)

  • Jakarta Persistence 3.0 (includes Eclipselink 3.0-RC1.) (jpa-3.0)

  • Jakarta XML Binding 3.0 (jaxb-3.0)

  • Jakarta Managed Beans 2.0 (managedBeans-2.0)

  • Jakarta Concurrency 2.0 (concurrent-2.0)

  • Jakarta Enterprise Beans Home 4.0 (ejbHome-4.0)

  • Jakarta Enterprise Beans Lite 4.0 (ejbLite-4.0)

  • Jakarta Bean Validation 3.0 (beanValidation-3.0)

  • Jakarta Contexts and Dependency Injection 3.0 (cdi-3.0)

  • Jakarta WebSocket 2.0 (websocket-2.0; currently the integration with CDI is not complete)

  • JDBC 4.2 & 4.3 (jdbc-4.2 & jdbc-4.3)

  • Jakarta Transactions 2.0 (transaction-2.0)

  • Jakarta JSON Binding 2.0 (jsonb-2.0)

  • Jakarta JSON Processing 2.0 (jsonp-2.0)

  • Jakarta Servlet 5.0 (servlet-5.0)

  • Jakarta Server Pages 3.0 (jsp-3.0)

  • Jakarta Expression Language 4.0 (el-4.0)

Enable the Jakarta EE 9 beta features in your app’s server.xml. You can enable the individual features you want or you can just add the Jakarta EE 9 convenience feature to enable all of the Jakarta EE 9 beta features at once:

<featureManager>
    <feature>jakartaee-9.0</feature>
</featureManager>

Or you can add the Web Profile convenience feature to enable all of the Jakarta EE 9 Web Profile beta features at once:

<featureManager>
    <feature>webProfile-9.0</feature>
</featureManager>

Or take a look at our Downloads page.

Try it now

To try out these Jakarta EE 9 features on Open Liberty in a lightweight package, just update your build tools to pull the Open Liberty Jakarta EE 9 Beta Features package instead of the main release. The beta works with Java SE 14, Java SE 11, or Java SE 8.

If you’re using Maven, here are the coordinates:

<dependency>
    <groupId>io.openliberty.beta</groupId>
    <artifactId>openliberty-jakartaee9</artifactId>
    <version>20.0.0.11-beta</version>
    <type>zip</type>
</dependency>

Or for Gradle:

dependencies {
    libertyRuntime group: 'io.openliberty.beta', name: 'openliberty-jakartaee9', version: '[20.0.0.11-beta,)'
}

Your feedback is welcomed

Let us know what you think on our mailing list. If you hit a problem, post a question on StackOverflow. If you hit a bug, please raise an issue.