From 1bae1e22560df737e650826a310cdbbed8d3c32f Mon Sep 17 00:00:00 2001 From: Andrew Rouse Date: Thu, 20 Jun 2024 17:08:18 +0100 Subject: [PATCH 1/5] Fix asciidoc indentation --- spec/src/main/asciidoc/release_notes.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/src/main/asciidoc/release_notes.asciidoc b/spec/src/main/asciidoc/release_notes.asciidoc index dfd9a3ee..b07e96f9 100644 --- a/spec/src/main/asciidoc/release_notes.asciidoc +++ b/spec/src/main/asciidoc/release_notes.asciidoc @@ -41,7 +41,7 @@ A full list of changes delivered in the 4.0 release can be found at link:https:/ ** New `Info` property: `summary` (https://github.com/eclipse/microprofile-open-api/issues/435[435]) ** New `License` property: `identifier` (https://github.com/eclipse/microprofile-open-api/issues/436[436]) ** New `Schema` properties: `booleanSchema`, `comment`, `constValue`, `contains`, `contentEncoding`, `contentMediaType`, `contentSchema`, `dependentRequired`, `dependentSchemas`, `elseSchema`, `examples`, `ifSchema`, `maxContains`, `minContains`, `patternProperties`, `prefixItems`, `propertyNames`, `schemaDialect`, `thenSchema`, `unevaluatedItems`, `unevaluatedProperties` (https://github.com/eclipse/microprofile-open-api/issues/584[584]), (https://github.com/eclipse/microprofile-open-api/issues/567[567]) -* New `Schema` methods for working with custom properties: `set(String, Object)`, `get(String)`, `setAll(Map)`, `getAll()` (https://github.com/eclipse/microprofile-open-api/issues/584[584]) +** New `Schema` methods for working with custom properties: `set(String, Object)`, `get(String)`, `setAll(Map)`, `getAll()` (https://github.com/eclipse/microprofile-open-api/issues/584[584]) ** New `Schema.SchemaType` enum value: `NULL` (https://github.com/eclipse/microprofile-open-api/issues/584[584]) ** New `SecuritySchema.Type` enum value: `MUTUALTLS` (https://github.com/eclipse/microprofile-open-api/issues/582[582]) * Annotation API changes, reflecting changes in the OpenAPI v3.1 document format From 080dc367d86da565931fe0c23c49806b06a662b0 Mon Sep 17 00:00:00 2001 From: Andrew Rouse Date: Thu, 20 Jun 2024 17:08:37 +0100 Subject: [PATCH 2/5] Restore section numbers Missing since version 2.0 --- spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc b/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc index b667e3cb..cac69283 100644 --- a/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc +++ b/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc @@ -35,6 +35,7 @@ endif::[] :sectnums!: include::license-efsl.adoc[] + :sectnums: == Introduction From 33cc7c49f0c70de3f51426beeadd0ee66de09975 Mon Sep 17 00:00:00 2001 From: Andrew Rouse Date: Thu, 20 Jun 2024 17:21:56 +0100 Subject: [PATCH 3/5] Have a single top-level release notes section With the section numbers restored, having the release notes comprise chapters 8-13 of the spec looks a bit silly. --- spec/src/main/asciidoc/release_notes.asciidoc | 39 ++++++++++--------- 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/spec/src/main/asciidoc/release_notes.asciidoc b/spec/src/main/asciidoc/release_notes.asciidoc index b07e96f9..0d1c82a1 100644 --- a/spec/src/main/asciidoc/release_notes.asciidoc +++ b/spec/src/main/asciidoc/release_notes.asciidoc @@ -16,13 +16,16 @@ // See the License for the specific language governing permissions and // limitations under the License. +[[release_notes]] +== Release Notes + [[release_notes_40]] -== Release Notes for MicroProfile OpenAPI 4.0 +=== Release Notes for MicroProfile OpenAPI 4.0 A full list of changes delivered in the 4.0 release can be found at link:https://github.com/eclipse/microprofile-open-api/milestone/6?closed=1[MicroProfile OpenAPI 4.0 Milestone] [[incompatible_changes_40]] -=== Incompatible Changes +==== Incompatible Changes * `/openapi` endpoint now serves documentation in OpenAPI v3.1 format (https://github.com/eclipse/microprofile-open-api/issues/333[333]) * Incompatible changes to the `Schema` model API, reflecting changes in the OpenAPI v3.1 document format (https://github.com/eclipse/microprofile-open-api/issues/584[584]) @@ -33,7 +36,7 @@ A full list of changes delivered in the 4.0 release can be found at link:https:/ * Minimum Java version increased to 11 [[api_changes_40]] -=== API/SPI changes +==== API/SPI changes * Model API changes, reflecting changes in the OpenAPI v3.1 document format ** New `OpenAPI` property: `webhooks` (https://github.com/eclipse/microprofile-open-api/issues/583[583]) @@ -59,7 +62,7 @@ A full list of changes delivered in the 4.0 release can be found at link:https:/ * Added `module-info` to the API jar (https://github.com/eclipse/microprofile-open-api/pull/577[577]) [[other_changes_40]] -=== Other changes +==== Other changes * Update references to the OpenAPI spec to point to v3.1 (https://github.com/eclipse/microprofile-open-api/pull/606[606]) * Update documentation and TCKs to reflect changes in OpenAPI v3.1 which don't affect the model API @@ -73,12 +76,12 @@ A full list of changes delivered in the 4.0 release can be found at link:https:/ * Replace references to "JAX-RS" with "Jakarta RESTful Web Services" (https://github.com/eclipse/microprofile-open-api/issues/574[574]) [[release_notes_31]] -== Release Notes for MicroProfile OpenAPI 3.1 +=== Release Notes for MicroProfile OpenAPI 3.1 A full list of changes delivered in the 3.1 release can be found at link:https://github.com/eclipse/microprofile-open-api/milestone/5?closed=1[MicroProfile OpenAPI 3.1 Milestone]. [[api_changes_31]] -=== API/SPI Changes +==== API/SPI Changes * Add `extensions` attribute to most annotations (https://github.com/eclipse/microprofile-open-api/issues/387[387]) * Improvements to the definition of security requirements (https://github.com/eclipse/microprofile-open-api/issues/483[483], https://github.com/eclipse/microprofile-open-api/issues/468[468]) @@ -89,7 +92,7 @@ A full list of changes delivered in the 3.1 release can be found at link:https:/ * Allow `@APIResponse` to be applied to a class, indicating that every resource method on that class has that response (https://github.com/eclipse/microprofile-open-api/issues/417[417]) [[other_changes_31]] -=== Other Changes +==== Other Changes * Add processing of some Jakarta Bean Validation annotations (https://github.com/eclipse/microprofile-open-api/issues/482[482]) * Define the precedence of the `mp.openapi.scan.*` config properties (https://github.com/eclipse/microprofile-open-api/issues/422[422]) @@ -99,22 +102,22 @@ A full list of changes delivered in the 3.1 release can be found at link:https:/ * Recommend that implementations provide a way to serve CORS headers on the `/openapi` endpoint (https://github.com/eclipse/microprofile-open-api/issues/416[416]) [[release_notes_30]] -== Release Notes for MicroProfile OpenAPI 3.0 +=== Release Notes for MicroProfile OpenAPI 3.0 A full list of changes delivered in the 3.0 release can be found at link:https://github.com/eclipse/microprofile-open-api/milestone/4?closed=1[MicroProfile OpenAPI 3.0 Milestone]. [[incompatible_changes_30]] -=== Incompatible Changes +==== Incompatible Changes This release aligns with Jakarta EE 9.1 (link:https://github.com/eclipse/microprofile-open-api/issues/487[487]), so it won’t work with earlier versions of Jakarta or Java EE. [[api_changes_30]] -==== API/SPI Changes +===== API/SPI Changes There are no functional changes introduced in this release, except the dependency updating from javax to jakarta. [[other_changes_30]] -==== Other Changes +===== Other Changes * Negative Test Scenario - @SchemaProperty Precedence Behaviour (link:https://github.com/eclipse/microprofile-open-api/issues/466[466]) * Use MediaType.APPLICATION_JSON instead of application/json in some TCKs (link:https://github.com/eclipse/microprofile-open-api/pull/471[471]) @@ -122,12 +125,12 @@ There are no functional changes introduced in this release, except the dependenc * TestNG 7.4.0 Assert.assertNotSame has a bug which causes ModelConstructionTest TCK to fail (link:https://github.com/eclipse/microprofile-open-api/issues/494[494]) [[release_notes_20]] -== Release Notes for MicroProfile OpenAPI 2.0 +=== Release Notes for MicroProfile OpenAPI 2.0 A full list of changes delivered in the 2.0 release can be found at link:https://github.com/eclipse/microprofile-open-api/milestone/2?closed=1[MicroProfile OpenAPI 2.0 Milestone]. [[incompatible_changes_20]] -=== Incompatible Changes +==== Incompatible Changes * Model interfaces that were deprecated in 1.1 have been removed: ** `Scopes` - this interface was replaced with `Map` because it did not need to be extensible (link:https://github.com/eclipse/microprofile-open-api/issues/328[328]) @@ -194,7 +197,7 @@ A full list of changes delivered in the 2.0 release can be found at link:https:/ *** `variables(ServerVariables variables)` - use `variables(Map)` instead (link:https://github.com/eclipse/microprofile-open-api/issues/245[245]) [[api_changes_20]] -=== API/SPI Changes +==== API/SPI Changes * The `@SchemaProperty` annotation has been added to allow the properties for a schema to be defined inline. (link:https://github.com/eclipse/microprofile-open-api/issues/360[360]). For example: ``` @@ -227,21 +230,21 @@ A full list of changes delivered in the 2.0 release can be found at link:https:/ ``` [[functional_changes_20]] -=== Functional Changes +==== Functional Changes * Getter methods on model interfaces that return a list or map now return a copy of the list/map containing the same items. This list/map CAN be immutable. (link:https://github.com/eclipse/microprofile-open-api/issues/240[240]) * Setter methods on model interfaces that take a list or a map as a parameter MUST not use the list/map instance directly (link:https://github.com/eclipse/microprofile-open-api/issues/284[284]) [[other_changes_20]] -=== Other Changes +==== Other Changes * JavaDoc updates to clarify the behaviour of getter methods on model interfaces that return a list or map ((link:https://github.com/eclipse/microprofile-open-api/issues/240[240]), link:https://github.com/eclipse/microprofile-open-api/pull/288[288]) * TCK updates to verify that getter methods on model interfaces return a list or map, return a copy of underlying collection ((link:https://github.com/eclipse/microprofile-open-api/issues/240[240]), link:https://github.com/eclipse/microprofile-open-api/pull/288[288]) [[release_notes_11]] -== Release Notes for MicroProfile OpenAPI 1.1 +=== Release Notes for MicroProfile OpenAPI 1.1 Changes include: @@ -266,7 +269,7 @@ Changes include: ** bug fixes, documentation updates, more convenience methods, deprecations, etc. [[release_notes_10]] -== Release Notes for MicroProfile OpenAPI 1.0 +=== Release Notes for MicroProfile OpenAPI 1.0 First official release of MP OpenAPI. Highlights of the release: From 123ed2113f71c8c04924fb93ceada3360f0541e8 Mon Sep 17 00:00:00 2001 From: Andrew Rouse Date: Thu, 20 Jun 2024 17:28:07 +0100 Subject: [PATCH 4/5] Fix alignment of configuration example --- spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc b/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc index cac69283..725bb27c 100644 --- a/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc +++ b/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc @@ -157,6 +157,7 @@ object of the resulting OpenAPI document using ``name``'s value as the key. + For example, in the case where an application wishes to represent Java ``Date``s in epoch milliseconds, the following configuration could be used (line escapes and indentation added for readability): ++ [source, json] ---- mp.openapi.schema.java.util.Date = { \ From ad1f18ebe591165a20c7f62f1c87464a13fe6474 Mon Sep 17 00:00:00 2001 From: Andrew Rouse Date: Fri, 21 Jun 2024 12:17:47 +0100 Subject: [PATCH 5/5] Update the list of annotations in the spec for 4.0 --- spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc b/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc index 725bb27c..fa9594b4 100644 --- a/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc +++ b/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc @@ -238,9 +238,12 @@ The following annotations are found in the https://github.com/eclipse/microprofi | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/links/Link.java[@Link] | Represents a design-time link for a response. | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/links/LinkParameter.java[@LinkParameter] | Represents a parameter to pass to the linked operation. | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Content.java[@Content] | Provides schema and examples for a particular media type. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DependentRequired.java[@DependentRequired] | Used within `@Schema` to indicate properties that are required if another property is present. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DependentSchema.java[@DependentSchema] | Used within `@Schema` to indicate additional rules that are required if a named property is present. | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DiscriminatorMapping.java[@DiscriminatorMapping] | Used to differentiate between other schemas which may satisfy the payload description. | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Encoding.java[@Encoding] | Single encoding definition to be applied to single Schema Object. | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/ExampleObject.java[@ExampleObject] | Illustrates an example of a particular content. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/PatternProperty.java[@PatternProperty] | Used within `@Schema` to define validation rules for properties whose names match a regular expression. | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Schema.java[@Schema] | Allows the definition of input and output data types. | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/SchemaProperty.java[@SchemaProperty] | Allows the definition of a property nested within a parent @Schema. | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/OpenAPIDefinition.java[@OpenAPIDefinition] | General metadata for an OpenAPI definition. @@ -249,6 +252,8 @@ The following annotations are found in the https://github.com/eclipse/microprofi | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameters.java[@Parameters] | Encapsulates input parameters. | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBody.java[@RequestBody] | Describes a single request body. | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBodySchema.java[@RequestBodySchema] | Describes a single request body with schema implementation class. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/PathItem.java[@PathItem] | Describes a set of operations available at the same location. Mostly only used to document webhooks as the paths for operations within the application can be discovered from Jakarta REST resources. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/PathItemOperation.java[@PathItemOperation] | Used within `@PathItem` to describe an operation. | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponse.java[@APIResponse] | Describes a single response from an API operation. | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponses.java[@APIResponses] | A container for multiple responses from an API operation. | https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponseSchema.java[@APIResponseSchema] | Describes a single response with schema implementation class from an API operation.