BETA BLOG - MicroProfile OpenAPI 3.1

[Azquelt]

The information you provide here will be included in the Open Liberty beta blog post (example), which will be published on openliberty.io/blog/, and potentially elsewhere, to promote this beta feature/function of Open Liberty. For this post to be included in the beta issue please make sure that this is completed by the end of Friday following the GM (Wednesday).

Please provide the following information the week before the GA/beta date (to allow for review and publishing):

1. Which Liberty feature(s) does your update relate to?

   Human-readable name (eg WebSockets feature): MicroProfile OpenAPI 3.1

   Short feature name (eg websockets-1.0): mpOpenAPI-3.1

2. Who is the target persona? Who do you expect to use the update? eg application developer, operations.

   Mostly application developers

3. Write a paragraph to summarises the update, including the following points:

OpenAPI is a standardised way of documenting REST APIs in a JSON or YAML format. MicroProfile OpenAPI helps you generate and serve OpenAPI documentation for your REST applications built using JAX-RS or Jakarta restfulWS. This can be useful for developers to test out the API during development, or for people using the API in production.

To use it, add the mpOpenAPI-3.1 feature to your server.xml, deploy your rest application and then visit /openapi on your liberty server to view the OpenAPI documentation, or visit /openapi/ui for a user interface that lets you browse through it. You can enhance the documentation using annotations to add things like textual descriptions to each method. The annotations are available as a maven dependency:

<dependency>
    <groupId>org.eclipse.microprofile.openapi</groupId>
    <artifactId>microprofile-openapi-api</artifactId>
    <version>3.1-RC2</version>
</dependency>

Version 3.1 is a small release which includes:

• Some Jakarta Bean Validation annotations will now be read and their restrictions will be added to object schemas
• Most annotations now include an extension attribute
• @SecurityRequirementsSet can now be used to document operations where authentication is optional or where more than one authentication mechanism is required

More information about MicroProfile OpenAPI can be found in

• the liberty guide
• the liberty documentation
• the javadoc
• the specification

What happens next?

• Add the label for the beta you're targeting: target:YY00X-beta.
• Make sure this blog post is linked back to the Epic for this feature/function.
• Your paragraph will be included in the beta blog post. It might be edited for style and consistency.
• You will be asked to review a draft before publication.
• If you would also like to write a standalone blog post about your update (highly recommended), raise an issue on the Open Liberty blogs repo. State in the issue that the blog post relates to a specific release so that we can ensure it is published on an appropriate date (it won't be the same day as the beta blog post).

[Azquelt]

I will be out for the next week, please contact @tevans78 for questions or review.

[Azquelt]

Related epic: #20040