Refactor OpenAPI documentation and update dependency version

Reorganize content on generating OpenAPI documents and improve clarity on annotation-based generation. Update version number for microprofile-openapi-api dependency.

Author: ttelang

modules/ROOT/pages/chapter04/chapter04.adoc

@@ -72,25 +72,21 @@ MicroProfile OpenAPI ensures your documentation stays synchronized with your imp
 
 == Generating OpenAPI documents
 
-Add annotations to your Jakarta REST resources to generate documentation with MicroProfile OpenAPI. This annotation-driven approach keeps your documentation synchronized with your code. When you update an endpoint, you update its documentation at the same time.
+MicroProfile OpenAPI provides multiple approaches to generate OpenAPI documentation. You can use annotations, static files, or a combination of both to create comprehensive API specifications.
 
 === Annotation-based generation
 
-You can use OpenAPI annotations to mark up your Jakarta REST classes and methods. MicroProfile OpenAPI then scans your application during the build time, automatically discovering the annotated endpoints, and producing a full OpenAPI specification.
+Add annotations to your Jakarta REST resources to generate documentation with MicroProfile OpenAPI. This annotation-driven approach keeps your documentation synchronized with your code. When you update an endpoint, you update its documentation at the same time.
+
+Annotate your Jakarta REST classes and methods with OpenAPI annotations. MicroProfile OpenAPI scans your application at build time, discovers annotated endpoints, and generates a complete OpenAPI specification automatically.
 
-This approach has several advantages:
+This approach offers several benefits:
 
 * Documentation lives alongside the code it describes
-* IDEs can provide support for autocomplete and validation features.
+* IDE support for autocomplete and validation
 * Compile-time checking ensures annotations remain valid
 * No separate specification files to maintain
 
-== Generating OpenAPI documents
-
-There are multiple ways in which you can generate OpenAPI documents. The most common way is to use annotations. This only requires augmenting your Jakarta Restful Web Services annotations with OpenAPI annotations. 
-
-Besides annotations, a predefined OpenAPI document may be provided in either YAML or JSON format. This so-called static model will be merged with the model generated by scanning for Jakarta REST endpoints and the combined result will be made available to clients. However, the annotation-based approach is recommended as it is more maintainable and easier to understand. Finally, you can filter out the resources you do not want to document using configuration.
-
 === Static OpenAPI files (optional)
 
 You can also provide a static OpenAPI document in `.yaml` or `.json` format at `META-INF/openapi.yaml` or `META-INF/openapi.json`. MicroProfile OpenAPI will merge this static content with the generated specification, which allows you to:
@@ -114,7 +110,7 @@ To use MicroProfile OpenAPI in your project, add the following Maven coordinates
 <dependency>
   <groupId>org.eclipse.microprofile.openapi</groupId>
   <artifactId>microprofile-openapi-api</artifactId>
-  <version>4.0</version>
+  <version>4.1</version>
   <scope>provided</scope>
 </dependency>
 ----
@@ -124,22 +120,20 @@ To use MicroProfile OpenAPI in your project, add the following Maven coordinates
 Use `<scope>provided</scope>` because your MicroProfile runtime already includes the implementation.
 ====
 
-== Using MicroProfile Open API in your project
+=== Configuring annotation scanning
 
-To document Jakarta RESTful Web Services using MicroProfile OpenAPI, we need to annotate the resource classes and methods with the OpenAPI annotation. 
-
-To use MicroProfile OpenAPI in your project, you need to add the following maven coordinates to your project:
+Add the following property to the `src/main/resources/META-INF/microprofile-config.properties` file:
 
-[source, xml]
+[source, properties]
 ----
-<dependency>
-  <groupId>org.eclipse.microprofile.openapi</groupId>
-  <artifactId>microprofile-openapi-api</artifactId>
-  <version>3.1.1</version>
-</dependency>
+mp.openapi.scan=true
 ----
 
-Below is an illustrative example of how you might annotate a method in the `ProductResource` class to achieve this documentation using MicroProfile OpenAPI annotations:
+This property tells MicroProfile OpenAPI to scan your classes for annotations and generate API documentation for them. 
+
+== Basic annotation example
+
+To document Jakarta RESTful Web Services using MicroProfile OpenAPI, annotate your resource classes and methods with OpenAPI annotations. The following example shows how to annotate a method in the `ProductResource` class:
 
 [source, java]
 ----
@@ -185,15 +179,6 @@ The annotations provide the following documentation:
 
 These annotations enrich the `ProductResource` class with metadata necessary for generating comprehensive OpenAPI documentation automatically.
 
-Add the following property to the `src/main/resources/META-INF/microprofile-config.properties` file:
-
-[source, properties]
-----
-mp.openapi.scan=true
-----
-
-This property tells MicroProfile OpenAPI to scan your classes for annotations and generate API documentation for them. 
-
 Build and run your application after configuring MicroProfile OpenAPI.
 
 == Viewing the generated documentation
@@ -1430,111 +1415,6 @@ public class SecuredProductResource {
 }
 ----
 
-==== Applying security to operations
-
-You can apply security requirements to individual operations or to entire resource classes.
-
-*Applying security to individual operations:*
-
-[source, java]
-----
-package io.microprofile.tutorial.store.product.resource;
-
-import org.eclipse.microprofile.openapi.annotations.Operation;
-import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
-import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
-import org.eclipse.microprofile.openapi.annotations.media.Content;
-import org.eclipse.microprofile.openapi.annotations.media.Schema;
-import jakarta.ws.rs.*;
-import jakarta.ws.rs.core.MediaType;
-import jakarta.ws.rs.core.Response;
-
-@Path("/products")
-public class SecuredProductResource {
-
-    @GET
-    @Path("/{id}")
-    @Produces(MediaType.APPLICATION_JSON)
-    @Operation(
-        summary = "Get product by ID",
-        description = "Retrieves detailed product information. Requires JWT authentication."
-    )
-    @SecurityRequirement(name = "bearerAuth")
-    @APIResponse(
-        responseCode = "200",
-        description = "Product found",
-        content = @Content(
-            mediaType = MediaType.APPLICATION_JSON,
-            schema = @Schema(implementation = Product.class)
-        )
-    )
-    @APIResponse(
-        responseCode = "401", 
-        description = "Unauthorized - Missing or invalid JWT token"
-    )
-    @APIResponse(
-        responseCode = "404", 
-        description = "Product not found"
-    )
-    public Response getSecuredProduct(@PathParam("id") Long id) {
-        // Security framework verifies JWT token
-        Product product = productService.findById(id);
-        
-        if (product == null) {
-            return Response.status(Response.Status.NOT_FOUND).build();
-        }
-        
-        return Response.ok(product).build();
-    }
-
-    @POST
-    @Consumes(MediaType.APPLICATION_JSON)
-    @Produces(MediaType.APPLICATION_JSON)
-    @Operation(
-        summary = "Create a new product",
-        description = "Creates a new product in the catalog. Requires OAuth2 write:products scope."
-    )
-    @SecurityRequirement(name = "oauth2", scopes = {"write:products"})
-    @APIResponse(
-        responseCode = "201",
-        description = "Product created successfully",
-        content = @Content(
-            mediaType = MediaType.APPLICATION_JSON,
-            schema = @Schema(implementation = Product.class)
-        )
-    )
-    @APIResponse(
-        responseCode = "401", 
-        description = "Unauthorized - Missing or invalid OAuth2 token"
-    )
-    @APIResponse(
-        responseCode = "403", 
-        description = "Forbidden - Token lacks required write:products scope"
-    )
-    @APIResponse(
-        responseCode = "400", 
-        description = "Bad request - Invalid product data"
-    )
-    public Response createSecuredProduct(
-        @Schema(description = "Product to create", required = true)
-        Product product
-    ) {
-        // Security framework verifies OAuth2 token and scopes
-        
-        if (product == null || product.getName() == null) {
-            return Response.status(Response.Status.BAD_REQUEST)
-                          .entity("Product name is required")
-                          .build();
-        }
-        
-        Product created = productService.create(product);
-        return Response.status(Response.Status.CREATED)
-                      .entity(created)
-                      .build();
-    }
-}
-----
-
 ==== Security in Swagger UI
 
 When you view the documented API in Swagger UI, security schemes appear in several ways: