diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Info.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Info.java index d4138912..de5a0bcb 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Info.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Info.java @@ -79,7 +79,8 @@ * The summary of the API. * * @return the summary for the API - **/ + * @since 4.0 + */ String summary() default ""; /** diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/License.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/License.java index b745e119..60dc7357 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/License.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/License.java @@ -44,6 +44,7 @@ * The license identifier used for the API. * * @return the identifier of the license + * @since 4.0 **/ String identifier() default ""; diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DependentRequired.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DependentRequired.java index 786dcdae..dc410ffb 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DependentRequired.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DependentRequired.java @@ -22,6 +22,7 @@ * properties with the names in {@link #requires()}. * * @see Schema#dependentRequired() + * @since 4.0 */ public @interface DependentRequired { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DependentSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DependentSchema.java index 4e7b0091..6ea7af42 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DependentSchema.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DependentSchema.java @@ -22,6 +22,7 @@ * validate against {@link #schema()}. * * @see Schema#dependentSchemas() + * @since 4.0 */ public @interface DependentSchema { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/PatternProperty.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/PatternProperty.java index e9531a53..9b0c7553 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/PatternProperty.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/PatternProperty.java @@ -26,6 +26,7 @@ * which validate against {@link #schema()}. * * @see Schema#patternProperties() + * @since 4.0 */ @Target({}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/Components.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/Components.java index 6f8ab497..b2dd8e10 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/Components.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Components.java @@ -488,6 +488,7 @@ default Components callbacks(Map callbacks) { * elsewhere in the OpenAPI document. * * @return a copy Map (potentially immutable) of path items + * @since 4.0 */ Map getPathItems(); @@ -497,6 +498,7 @@ default Components callbacks(Map callbacks) { * * @param pathItems * a map of path items + * @since 4.0 */ void setPathItems(Map pathItems); @@ -507,6 +509,7 @@ default Components callbacks(Map callbacks) { * @param pathItems * a map of path items * @return the current Schema instance + * @since 4.0 */ default Components pathItems(Map pathItems) { setPathItems(pathItems); diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Info.java index 2644aeb8..6d8f58dd 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Info.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Info.java @@ -204,6 +204,7 @@ default Info version(String version) { * Returns the summary of the exposed API from this Info instance. * * @return the summary of the exposed API + * @since 4.0 **/ String getSummary(); @@ -212,6 +213,7 @@ default Info version(String version) { * * @param summary * the summary of the exposed API + * @since 4.0 */ void setSummary(String summary); @@ -221,6 +223,7 @@ default Info version(String version) { * @param summary * the summary for the exposed API * @return this Info instance + * @since 4.0 */ default Info summary(String summary) { setSummary(summary); diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/License.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/License.java index 38f20940..0bd93df0 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/License.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/License.java @@ -58,7 +58,8 @@ default License name(String name) { * Returns the license identifier for this License instance that is used for the API. * * @return the license identifier used for the API - **/ + * @since 4.0 + */ String getIdentifier(); /** @@ -66,6 +67,7 @@ default License name(String name) { * * @param identifier * the license identifier used for the API + * @since 4.0 */ void setIdentifier(String identifier); @@ -75,6 +77,7 @@ default License name(String name) { * @param identifier * the license identifier used for the API * @return this License instance + * @since 4.0 */ default License identifier(String identifier) { setIdentifier(identifier); diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java index 10bcf4b7..ed8daad1 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java @@ -44,7 +44,7 @@ public interface Schema extends Extensible, Constructible, Reference { /** - * The values allowed for the in field. + * The values allowed for the {@code type} field. */ enum SchemaType { INTEGER("integer"), NUMBER("number"), BOOLEAN("boolean"), STRING("string"), OBJECT("object"), ARRAY( @@ -2063,6 +2063,7 @@ default Schema examples(List examples) { * @param propertyName * the property name * @return the value of the named property, or {@code null} if a property with the given name is not set + * @since 4.0 */ Object get(String propertyName); @@ -2103,6 +2104,7 @@ default Schema examples(List examples) { * @param value * the value to set, or {@code null} to remove the property * @return the current Schema instance + * @since 4.0 */ Schema set(String propertyName, Object value); @@ -2113,6 +2115,7 @@ default Schema examples(List examples) { * into a {@code Map}. * * @return a {@code Map} of property names to their corresponding values + * @since 4.0 */ Map getAll(); @@ -2124,6 +2127,7 @@ default Schema examples(List examples) { * @param allProperties * the properties to set. Each value in the map must be valid according to the rules in * {@link #set(String, Object)} + * @since 4.0 */ void setAll(Map allProperties); } diff --git a/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc b/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc index f0879094..b667e3cb 100644 --- a/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc +++ b/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc @@ -17,7 +17,7 @@ // limitations under the License. // -:authors: Arthur De Magalhaes (Spec Lead), Eric Wittmann, Anna Safonov, Matt Gill, Ivan Junckes Filho, Jérémie Bresson, Jana Manoharan, Rui Qi Wang, Tommy Wojtczak, Martin Smithson, Michael Edgar +:authors: Arthur De Magalhaes (Spec Lead), Eric Wittmann, Anna Safonov, Matt Gill, Ivan Junckes Filho, Jérémie Bresson, Jana Manoharan, Rui Qi Wang, Tommy Wojtczak, Martin Smithson, Michael Edgar, Andrew Rouse :version-label!: :sectanchors: :doctype: book @@ -211,7 +211,7 @@ library and wish to take advantage to the official MP OpenAPI interfaces. ==== Quick overview of annotations -The following annotations are found in the https://github.com/eclipse/microprofile-open-api/tree/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations[org.eclipse.microprofile.openapi.annotations] package. +The following annotations are found in the https://github.com/eclipse/microprofile-open-api/tree/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations[org.eclipse.microprofile.openapi.annotations] package. [cols="1,4"] |=== @@ -387,7 +387,7 @@ post: '*/*': schema: $ref: '#/components/schemas/User' - required: true + required: true responses: default: description: no description @@ -461,7 +461,7 @@ public class ServersResource { .Output for Sample 1 [source, yaml] ---- -openapi: 3.0.2 +openapi: 3.1.0 servers: - url: http://{var1}.definition1/{var2} description: definition server 1 @@ -614,18 +614,14 @@ maxItems = b` | `minProperties = a + maxProperties = b` | `@DecimalMax(value = a)` | `number` or `integer` | `maximum = a` -| `@DecimalMax(value = a, exclusive = false)` | `number` or `integer` | `maximum = a + -exclusiveMaximum = true` +| `@DecimalMax(value = a, inclusive = false)` | `number` or `integer` | `exclusiveMaximum = a` | `@DecimalMin(value = a)` | `number` or `integer` | `minimum = a` -| `@DecimalMin(value = a, exclusive = false)` | `number` or `integer` | `minimum = a + -exclusiveMinimum = true` +| `@DecimalMin(value = a, inclusive = false)` | `number` or `integer` | `exclusiveMinimum = a` | `@Max(a)` | `number` or `integer` | `maximum = a` | `@Min(a)` | `number` or `integer` | `minimum = a` -| `@Negative` | `number` or `integer` | `maximum = 0 + -exclusiveMaximum = true` +| `@Negative` | `number` or `integer` | `exclusiveMaximum = 0` | `@NegativeOrZero` | `number` or `integer` | `maximum = 0` -| `@Positive` | `number` or `integer` | `minimum = 0 + -exclusiveMinimum = true` +| `@Positive` | `number` or `integer` | `exclusiveMinimum = 0` | `@PositiveOrZero` | `number` or `integer` | `minimum = 0` |=== @@ -656,7 +652,7 @@ This is in addition to the default locations defined by https://github.com/eclip === Programming model Application developers are able to provide OpenAPI elements via Java POJOs. The -complete set of models are found in the https://github.com/eclipse/microprofile-open-api/tree/master/api/src/main/java/org/eclipse/microprofile/openapi/models[org.eclipse.microprofile.openapi.models] package. +complete set of models are found in the https://github.com/eclipse/microprofile-open-api/tree/main/api/src/main/java/org/eclipse/microprofile/openapi/models[org.eclipse.microprofile.openapi.models] package. ==== OASFactory diff --git a/spec/src/main/asciidoc/release_notes.asciidoc b/spec/src/main/asciidoc/release_notes.asciidoc index 08a2ba32..dfd9a3ee 100644 --- a/spec/src/main/asciidoc/release_notes.asciidoc +++ b/spec/src/main/asciidoc/release_notes.asciidoc @@ -41,6 +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.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