Merge pull request #644 from Azquelt/spec-fixes

Fix spec mistakes found in final readthrough

Author: Azquelt

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 "";
 
     /**

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 "";
 

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 {
 

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 {
 

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)

api/src/main/java/org/eclipse/microprofile/openapi/models/Components.java

@@ -488,6 +488,7 @@ default Components callbacks(Map<String, Callback> callbacks) {
      * elsewhere in the OpenAPI document.
      *
      * @return a copy Map (potentially immutable) of path items
+     * @since 4.0
      */
     Map<String, PathItem> getPathItems();
 
@@ -497,6 +498,7 @@ default Components callbacks(Map<String, Callback> callbacks) {
      *
      * @param pathItems
      *            a map of path items
+     * @since 4.0
      */
     void setPathItems(Map<String, PathItem> pathItems);
 
@@ -507,6 +509,7 @@ default Components callbacks(Map<String, Callback> callbacks) {
      * @param pathItems
      *            a map of path items
      * @return the current Schema instance
+     * @since 4.0
      */
     default Components pathItems(Map<String, PathItem> pathItems) {
         setPathItems(pathItems);

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);

api/src/main/java/org/eclipse/microprofile/openapi/models/info/License.java

@@ -58,14 +58,16 @@ 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();
 
     /**
      * Sets the license identifier for this License instance that is used for the API.
      *
      * @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);

api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java

@@ -44,7 +44,7 @@
 public interface Schema extends Extensible<Schema>, Constructible, Reference<Schema> {
 
     /**
-     * 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<Object> 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<Object> 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<Object> examples) {
      * into a {@code Map}.
      *
      * @return a {@code Map} of property names to their corresponding values
+     * @since 4.0
      */
     Map<String, ?> getAll();
 
@@ -2124,6 +2127,7 @@ default Schema examples(List<Object> 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<String, ?> allProperties);
 }

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
 

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<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