Update chapter04.adoc about MicroProfile OpenAPI 4.1 with the latest features from OpenAPI 3.0#63
Update chapter04.adoc about MicroProfile OpenAPI 4.1 with the latest features from OpenAPI 3.0#63ttelang wants to merge 11 commits intomicroprofile:mainfrom
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.
| === 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.
Updated the version number from 4.1 to 4.0 and added a note about the new features and clarifications in MicroProfile OpenAPI 4.0.
Simplified the example by using the `getExtension()` method added in 4.1, along with the preexisting `addExtension()` method, rather than handling the map of extensions directly.
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.