Skip to content

Commit 5499b0e

Browse files
authored
Improve clarity in chapter 04 documentation
Refine chapter summary and core concepts for clarity and conciseness.
1 parent 2f545c8 commit 5499b0e

1 file changed

Lines changed: 7 additions & 12 deletions

File tree

modules/ROOT/pages/chapter04/chapter04.adoc

Lines changed: 7 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1337,7 +1337,7 @@ This makes it easy for API consumers to understand authentication requirements a
13371337

13381338
== Summary
13391339

1340-
In this chapter, you explored how MicroProfile OpenAPI 4.1 enables automatic generation of comprehensive, OpenAPI v3.1-compliant documentation for your RESTful web services. When you integrate MicroProfile OpenAPI into your Jakarta REST applications, you can create well-documented APIs that are discoverable, understandable, and easy to consume.
1340+
In this chapter, you explored how MicroProfile OpenAPI 4.1 enables automatic generation of comprehensive, OpenAPI v3.1-compliant documentation for your RESTful web services.
13411341

13421342
=== Core concepts mastered
13431343

@@ -1355,20 +1355,17 @@ You learned how MicroProfile OpenAPI 4.1 fully supports OpenAPI v3.1, bringing i
13551355

13561356
You explored how MicroProfile OpenAPI 4.1 provides native support for Java records, which allows you to use modern, immutable data carriers like `CategoryRecord` with automatic schema generation. You learned to combine `@Schema` annotations with `@NotNull` validation to create well-documented, type-safe data models.
13571357

1358-
*Enhanced type safety*
1359-
You discovered how explicit `@Target` meta-annotations improve compile-time checking and IDE support, which helps you use OpenAPI annotations correctly and prevents misuse during development.
1360-
13611358
*JSON Schema dialects*
13621359

1363-
You learned to specify JSON Schema dialects programmatically using the `jsonSchemaDialect` property, which enables better compatibility with external validators and tooling. You explored the differences between the default OpenAPI 3.1 dialect and full JSON Schema 2020-12 support.
1360+
You learned to specify JSON Schema dialects programmatically using the `jsonSchemaDialect` property enabling better compatibility with external validators and tooling.
13641361

13651362
*Vendor extensions*
13661363

1367-
You explored the new `hasExtension()` and `getExtension()` convenience methods that simplify working with vendor extensions (`x-` properties). Through practical examples with `ExtensionFilter`, you learned how to read existing extensions and dynamically add metadata to your OpenAPI documentation for API gateway configuration, monitoring, and policy enforcement.
1364+
You explored the new `hasExtension()` and `getExtension()` convenience methods that simplify working with vendor extensions (`x-` properties). Through practical examples with `ExtensionFilter`, you learned how to read existing extensions and dynamically add metadata to your OpenAPI documentation.
13681365

13691366
*Asynchronous operations*
13701367

1371-
You learned to document asynchronous operations using the `@Callback` annotation, which is essential for webhook-style APIs. Using the `AsyncProductRequest` and `ProcessResult` models, you documented how your API initiates async processing and notifies clients when operations complete.
1368+
You learned to document asynchronous operations using the `@Callback` annotation. You documented how your API initiates async processing and notifies clients when operations complete.
13721369

13731370
*Security schemes*
13741371

@@ -1380,16 +1377,14 @@ Having finished this chapter, you can now:
13801377

13811378
* Generate OpenAPI 3.1 specifications automatically from Jakarta REST code
13821379
* Document endpoints using `@Operation`, `@APIResponse`, and `@Tag` annotations
1383-
* Construct type-safe schemas using Java records and `@Schema`
1384-
* Handle flexible schemas for dynamic attributes
1385-
* Document asynchronous operations with callbacks
1386-
* Configure multiple security schemes
13871380
* Add OAS filters for dynamic documentation
13881381
* Test APIs interactively with Swagger UI
1382+
* Document asynchronous operations with callbacks
1383+
* Configure multiple security schemes
13891384

13901385
=== Practical applications
13911386

1392-
MicroProfile OpenAPI 4.1's alignment with OpenAPI v3.1 guarentees your API documentation ahdres to the latest standards in the API landscape. This annotation-driven approach keeps documentation in sync with your implementation, thereby avoiding the common problem of outdated specifications. The generated OpenAPI documents facilities:
1387+
MicroProfile OpenAPI 4.1's alignment with OpenAPI v3.1 guarentees your API documentation adheres to the latest standards in the API landscape. This annotation-driven approach keeps documentation in sync with your implementation, thereby avoiding the common problem of outdated specifications. The generated OpenAPI documents facilities:
13931388

13941389
* Automatic client SDK generation across multiple programming languages
13951390
* Interactive API exploration via Swagger UI

0 commit comments

Comments
 (0)