Update chapter04.adoc about MicroProfile OpenAPI 4.1 with the latest features from OpenAPI 3.0#63
Conversation
Improved clarity and readability of the MicroProfile OpenAPI section by rephrasing sentences and enhancing consistency in terminology.
Updated the chapter content to improve clarity and correctness, including rephrasing sentences and fixing typographical errors.
Rephrase and clarify the explanation of the OpenAPI Specification and its benefits, improving readability and consistency.
| == New features in MicroProfile OpenAPI 4.1 | ||
|
|
||
| MicroProfile OpenAPI 4.1 introduces several enhancements that improve developer productivity and align with the OpenAPI v3.1 specification. These features simplify API documentation, add support for modern Java language features, and provide better schema validation capabilities. |
There was a problem hiding this comment.
Support for OpenAPI v3.1 was actually first included in MP OpenAPI 4.0.
You can reference the Release Notes for more details.
MP OpenAPI 4.1 really didn't add very much, but 4.0 was a major release so I think it is worth calling out these new features, just be aware that they were added in 4.0, not 4.1.
| import java.util.LinkedHashMap; | ||
| import java.util.Map; | ||
|
|
||
| public class ExtensionFilter implements OASFilter { |
There was a problem hiding this comment.
This example could be simplified by using the getExtension method added in 4.1, along with the preexisting addExtension method, rather than handling the map of extensions directly.
| === Documenting asynchronous operations with callbacks | ||
|
|
||
| MicroProfile OpenAPI 4.1 supports documenting asynchronous operations that use callbacks. Callbacks prove useful for webhook-style APIs where your service initiates an asynchronous process and notifies the client when it completes by making an HTTP request back to a URL provided by the client. |
There was a problem hiding this comment.
Support for callbacks was not new in 4.1 (or 4.0).
@Callback documents a callback that can be set up using an operation.
4.0 added support for webhooks, which document a callback which can be set up via some out of band mechanism (e.g. through a form on a web page). The OpenAPI document may include information on how to set the webhook up.
| === Documenting security schemes | ||
|
|
||
| Security is a critical aspect of API documentation. MicroProfile OpenAPI 4.1 provides comprehensive support for documenting various security schemes including API keys, HTTP authentication, OAuth2, and OpenID Connect. |
There was a problem hiding this comment.
This is still in the "what's new" section?
If so, we should document what was actually added, otherwise you give the impression that security schemes were new in 4.0, whereas actually it was only a small tweak.
| ==== Applying security to operations | ||
|
|
||
| You can apply security requirements to individual operations or to entire resource classes. | ||
|
|
||
| *Applying security to individual operations:* |
There was a problem hiding this comment.
Whenever we talk about applying security requirements in OpenAPI, we need to be very clear that OpenAPI only documents security requirements, it doesn't enforce anything.
The user must first implement access controls, and then use OpenAPI to document to their end users how to authenticate with the API.
Reorganize content on generating OpenAPI documents and improve clarity on annotation-based generation. Update version number for microprofile-openapi-api dependency.
Removed the section on configuring annotation scanning and added a note about its default state.
Refactored API response annotations for clarity and updated a note about usage of @APIResponses with `extensions' meta data fields.
Updated practical use cases for filters with more detailed examples and added notes on tool integration.
Removed section on new features in MicroProfile OpenAPI 4.1 and updated related content for clarity.
2 participants
This PR contains is for updating Chapter 04 of the official MicroProfile 7.1 API Tutorial with the coverage the latest feature and enhancements in MicroProfile OpenAPI 4.1.
This chapter provides detailed coverage of OpenAPI Specification integration with Jakarta RESTful Web Services, focusing on annotation-driven API documentation generation.
Topics Updated
oneOf,anyOf,allOf)Optional<T>support for nullable fields@Targetmeta-annotation improvementsCustomModelReaderimplementationhasExtension()andgetExtension()convenience methodsExtensionFilterimplementation for dynamic documentation@Callbackand@CallbackOperationusageI would be sharing another PR for the associated code changes in next few days.