Support extensions as nested annotations for extensible models

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

@@ -22,6 +22,7 @@
 import java.lang.annotation.Target;
 
 import org.eclipse.microprofile.openapi.annotations.callbacks.Callback;
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
 import org.eclipse.microprofile.openapi.annotations.headers.Header;
 import org.eclipse.microprofile.openapi.annotations.links.Link;
 import org.eclipse.microprofile.openapi.annotations.media.ExampleObject;
@@ -105,4 +106,14 @@
      * @return the reusable Callback objects.
      */
     Callback[] callbacks() default {};
+
+    /**
+     * The list of optional extensions.
+     *
+     * @return an optional array of extensions
+     * 
+     * @since 3.1
+     */
+    Extension[] extensions() default {};
+
 }

api/src/main/java/org/eclipse/microprofile/openapi/annotations/ExternalDocumentation.java

@@ -23,6 +23,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
+
 /**
  * This annotation allows referencing an external resource for extended documentation.
  * <p>
@@ -56,4 +58,12 @@
      **/
     String url() default "";
 
+    /**
+     * The list of optional extensions.
+     *
+     * @return an optional array of extensions
+     * 
+     * @since 3.1
+     */
+    Extension[] extensions() default {};
 }

api/src/main/java/org/eclipse/microprofile/openapi/annotations/OpenAPIDefinition.java

@@ -23,6 +23,7 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
 import org.eclipse.microprofile.openapi.annotations.info.Info;
 import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
 import org.eclipse.microprofile.openapi.annotations.servers.Server;
@@ -87,4 +88,13 @@
      * @return the element with a set of reusable objects for different aspects of the OAS.
      */
     Components components() default @Components;
+
+    /**
+     * The list of optional extensions.
+     *
+     * @return an optional array of extensions
+     * 
+     * @since 3.1
+     */
+    Extension[] extensions() default {};
 }

api/src/main/java/org/eclipse/microprofile/openapi/annotations/Operation.java

@@ -23,6 +23,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
+
 /**
  * Describes a single API operation on a path.
  * 
@@ -75,4 +77,13 @@
      * @return whether or not this operation is hidden
      */
     boolean hidden() default false;
+
+    /**
+     * The list of optional extensions.
+     *
+     * @return an optional array of extensions
+     * 
+     * @since 3.1
+     */
+    Extension[] extensions() default {};
 }

api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callback.java

@@ -24,6 +24,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
+
 /**
  * This object represents a callback URL that will be invoked.
  * 
@@ -74,4 +76,13 @@
      * @return reference to a callback object definition
      **/
     String ref() default "";
+
+    /**
+     * The list of optional extensions.
+     *
+     * @return an optional array of extensions
+     * 
+     * @since 3.1
+     */
+    Extension[] extensions() default {};
 }

api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/package-info.java

@@ -44,6 +44,6 @@
  * </pre>
  */
 
-@org.osgi.annotation.versioning.Version("1.0")
+@org.osgi.annotation.versioning.Version("1.1")
 @org.osgi.annotation.versioning.ProviderType
 package org.eclipse.microprofile.openapi.annotations.callbacks;

api/src/main/java/org/eclipse/microprofile/openapi/annotations/extensions/Extension.java

@@ -24,17 +24,62 @@
 import java.lang.annotation.Target;
 
 /**
- * A named extension that should be added to the OpenAPI definition.
+ * A named extension that should be added to the OpenAPI definition. The names of all extensions MUST begin with
+ * {@code x-} or else an invalid document will potentially be created.
+ * 
+ * <p>
+ * Although this annotation may currently be placed directly on a Java language element target, application developers
+ * should instead utilize the {@code extensions} property of the particular annotation that corresponds to the model
+ * being extended. Use of the annotation directly on a Java element is often ambiguous and it may result in the
+ * extension being added to an incorrect location in the OpenAPI model. Future releases of MicroProfile OpenAPI may
+ * remove the capability of placing this annotation directly on a Java element.
+ * 
+ * <p>
+ * When {@literal @}Extension annotations are used both directly on a Java element as well as within another annotation
+ * that targets the same Java element, implementations will apply only the nested extensions to the resulting model.
+ * 
+ * <p>
+ * Example of <em>preferred</em> use with {@literal @}Extension nested within an {@literal @}Schema annotation:
+ * 
+ * <pre>
+ * class MyPojo {
+ *
+ *     {@literal @}Schema(
+ *         type = SchemaType.STRING,
+ *         extensions = {@literal @}Extension(
+ *             name = "x-custom-property",
+ *             value = "custom-value")
+ *     String property1;
+ * 
+ * }
+ * </pre>
+ * 
+ * <p>
+ * Example of <em>deprecated</em> use with {@literal @}Extension placed directly on a field implied to be a schema
+ * property:
+ * 
+ * <pre>
+ * class MyPojo {
+ *
+ *     {@literal @}Extension(
+ *         name = "x-custom-property",
+ *         value = "custom-value")
+ *     String property1;
+ *
+ * }
+ * </pre>
+ * 
  */
 @Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 @Repeatable(Extensions.class)
 public @interface Extension {
 
     /**
-     * A name for the extension.
+     * A name for the extension. The names of all extensions MUST begin with {@code x-} or else an invalid document will
+     * potentially be created.
      *
-     * @return an option name for these extensions - will be prefixed with "x-"
+     * @return an option name for these extensions - must be prefixed with {@code x-}
      */
     String name();
 

api/src/main/java/org/eclipse/microprofile/openapi/annotations/headers/Header.java

@@ -22,6 +22,7 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
 import org.eclipse.microprofile.openapi.annotations.media.Schema;
 
 /**
@@ -92,4 +93,12 @@
      **/
     String ref() default "";
 
+    /**
+     * The list of optional extensions.
+     *
+     * @return an optional array of extensions
+     * 
+     * @since 3.1
+     */
+    Extension[] extensions() default {};
 }

api/src/main/java/org/eclipse/microprofile/openapi/annotations/headers/package-info.java

@@ -26,6 +26,6 @@
  * </pre>
  */
 
-@org.osgi.annotation.versioning.Version("1.0")
+@org.osgi.annotation.versioning.Version("1.1")
 @org.osgi.annotation.versioning.ProviderType
 package org.eclipse.microprofile.openapi.annotations.headers;

api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Contact.java

@@ -22,6 +22,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
+
 /**
  * Contact information for the exposed API.
  * 
@@ -52,4 +54,12 @@
      **/
     String email() default "";
 
+    /**
+     * The list of optional extensions.
+     *
+     * @return an optional array of extensions
+     * 
+     * @since 3.1
+     */
+    Extension[] extensions() default {};
 }

api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Info.java

@@ -22,6 +22,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
+
 /**
  * This annotation provides metadata about the API, and maps to the Info object in OpenAPI Specification 3.
  * 
@@ -73,4 +75,12 @@
      **/
     String version();
 
+    /**
+     * The list of optional extensions.
+     *
+     * @return an optional array of extensions
+     * 
+     * @since 3.1
+     */
+    Extension[] extensions() default {};
 }

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

@@ -22,6 +22,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
+
 /**
  * License information for the exposed API.
  * 
@@ -45,4 +47,12 @@
      **/
     String url() default "";
 
+    /**
+     * The list of optional extensions.
+     *
+     * @return an optional array of extensions
+     * 
+     * @since 3.1
+     */
+    Extension[] extensions() default {};
 }

api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/package-info.java

@@ -34,6 +34,6 @@
  * </pre>
  */
 
-@org.osgi.annotation.versioning.Version("1.0")
+@org.osgi.annotation.versioning.Version("1.1")
 @org.osgi.annotation.versioning.ProviderType
 package org.eclipse.microprofile.openapi.annotations.info;

api/src/main/java/org/eclipse/microprofile/openapi/annotations/links/Link.java

@@ -22,6 +22,7 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
 import org.eclipse.microprofile.openapi.annotations.servers.Server;
 
 /**
@@ -103,4 +104,12 @@
      **/
     String ref() default "";
 
+    /**
+     * The list of optional extensions.
+     *
+     * @return an optional array of extensions
+     * 
+     * @since 3.1
+     */
+    Extension[] extensions() default {};
 }

api/src/main/java/org/eclipse/microprofile/openapi/annotations/links/package-info.java

@@ -31,6 +31,6 @@
  * </pre>
  */
 
-@org.osgi.annotation.versioning.Version("1.0")
+@org.osgi.annotation.versioning.Version("1.1")
 @org.osgi.annotation.versioning.ProviderType
 package org.eclipse.microprofile.openapi.annotations.links;

api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Encoding.java

@@ -22,6 +22,7 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
 import org.eclipse.microprofile.openapi.annotations.headers.Header;
 
 /**
@@ -103,4 +104,12 @@
      */
     Header[] headers() default {};
 
+    /**
+     * The list of optional extensions.
+     *
+     * @return an optional array of extensions
+     * 
+     * @since 3.1
+     */
+    Extension[] extensions() default {};
 }

api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/ExampleObject.java

@@ -22,6 +22,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
+
 /**
  * This object illustrates an example of a particular content
  * 
@@ -91,4 +93,12 @@
      **/
     String ref() default "";
 
+    /**
+     * The list of optional extensions.
+     *
+     * @return an optional array of extensions
+     * 
+     * @since 3.1
+     */
+    Extension[] extensions() default {};
 }

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

@@ -25,6 +25,7 @@
 
 import org.eclipse.microprofile.openapi.annotations.ExternalDocumentation;
 import org.eclipse.microprofile.openapi.annotations.enums.SchemaType;
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
 
 /**
  * The Schema Object allows the definition of input and output data types. These types can be objects, but also
@@ -399,4 +400,13 @@
      * @since 2.0
      */
     SchemaProperty[] properties() default {};
+
+    /**
+     * The list of optional extensions.
+     *
+     * @return an optional array of extensions
+     * 
+     * @since 3.1
+     */
+    Extension[] extensions() default {};
 }