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.
|
|
||
| Use the `mp.openapi.scan.exclude.packages` and `mp.openapi.scan.exclude.classes` configuration properties to exclude specific resources from documentation. This approach proves useful for internal or administrative endpoints you do not want to expose in your public API specification. | ||
|
|
||
| == Using MicroProfile OpenAPI in your project |
There was a problem hiding this comment.
The title for this section is the same as the title for the next section.
| * `@APIResponses`: Documents possible HTTP responses from the operation | ||
| * `@APIResponse`: Defines a specific response with status code and content |
There was a problem hiding this comment.
In the example above, you don't actually need the @APIResponses annotation, you can just write the @APIResponse annotation twice on the method:
@GET
@Produces(MediaType.APPLICATION_JSON)
@Operation(summary = "List all products", description = "Retrieves a list of all available products")
@APIResponse(
responseCode = "200",
description = "Successful, list of products found",
content = @Content(mediaType = "application/json",
schema = @Schema(implementation = Product.class))
)
@APIResponse(
responseCode = "400",
description = "Unsuccessful, no products found",
content = @Content(mediaType = "application/json")
)
public List<Product> getAllProducts() {The only time you need to explicitly include @APIResponses is if you want to use the extensions field.
| Add the following property to the `src/main/resources/META-INF/microprofile-config.properties` file: | ||
|
|
||
| [source, properties] | ||
| ---- | ||
| mp.openapi.scan=true | ||
| ---- |
There was a problem hiding this comment.
This is a bit surprising, the spec only defines the mp.openapi.scan.disabled config property, which defaults to false. (i.e. scanning enabled)
Did some implementations need this? If it's needed in some cases, it probably makes sense to keep it in the tutorial.
| The `/openapi` endpoint returns the OpenAPI specification generated from the annotations in your source code. It returns information in YAML format. | ||
|
|
||
| When we access the `http://localhost:5050/openapi` URL, we should see the API documentation that was generated by MicroProfile OpenAPI: | ||
| When you access the `\http://localhost:9080/openapi` URL, you see the API documentation that MicroProfile OpenAPI generated: |
There was a problem hiding this comment.
is the \ before http deliberate here?
There was a problem hiding this comment.
Ah, it stops it being rendered as a hyperlink, that makes sense here.
| == 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.
| * Dynamic documentation enrichment: Add computed metadata based on existing extensions | ||
| * Validation: Log warnings for operations missing required extensions | ||
| * Policy enforcement: Ensure all admin operations have proper security annotations | ||
| * Metrics: Count operations by type or collect extension statistics |
There was a problem hiding this comment.
The others seem plausible, I'm not sure about this one.
| === 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.
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.