Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

More spec fixes #647

Merged
merged 5 commits into from
Jun 21, 2024
Merged

More spec fixes #647

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1bae1e2
Fix asciidoc indentation
Azquelt Jun 20, 2024
080dc36
Restore section numbers
Azquelt Jun 20, 2024
33cc7c4
Have a single top-level release notes section
Azquelt Jun 20, 2024
123ed21
Fix alignment of configuration example
Azquelt Jun 20, 2024
ad1f18e
Update the list of annotations in the spec for 4.0
Azquelt Jun 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ endif::[]

:sectnums!:
include::license-efsl.adoc[]

:sectnums:

== Introduction
Expand Down Expand Up @@ -156,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 = { \
Expand Down Expand Up @@ -236,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.
Expand All @@ -247,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.
Expand Down
41 changes: 22 additions & 19 deletions spec/src/main/asciidoc/release_notes.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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])
Expand All @@ -33,15 +36,15 @@ 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])
** New `Components` property: `pathItems` (https://github.com/eclipse/microprofile-open-api/issues/437[437])
** 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<String, ?>)`, `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<String, ?>)`, `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
Expand All @@ -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
Expand All @@ -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])
Expand All @@ -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])
Expand All @@ -99,35 +102,35 @@ 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])
* TCK Tag Collection Test contains() side effect (link:https://github.com/eclipse/microprofile-open-api/issues/453[453])
* 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<String, ServerVariable>` because it did not need to be extensible (link:https://github.com/eclipse/microprofile-open-api/issues/328[328])
Expand Down Expand Up @@ -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:
```
Expand Down Expand Up @@ -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:

Expand All @@ -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:

Expand Down