MicroProfile OpenAPI Models

README.adoc

@@ -22,3 +22,5 @@
 This specification aims at providing a unified Java API for the OpenAPI v3
 specification (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md),
 that all application developers can use to expose their API documentation.
+
+The specification is composed of annotations, models, and configuration interfaces.

api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.eclipse.microprofile.openapi;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.spi.OASFactoryResolver;
+
+public final class OASFactory {
+
+    private static final OASFactoryResolver INSTANCE = OASFactoryResolver.instance();
+
+    public static <T extends Constructible> T createObject(Class<T> clazz){
+		return INSTANCE.createObject(clazz);
+	}
+
+}

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

@@ -44,33 +44,33 @@
 
     /**
      * The Content-Type for encoding a specific property.
+     * Default value depends on the property type: 
+	 * i.e. for binary string - contentType is application/octet-stream, for primitive types - text/plain, for object - application/json.
      **/
     String contentType() default "";
 
     /**
-     * Describes how a specific property value will be serialized depending on its type
-     **/
+    * Style describes how the encoding value will be serialized depending on the type of the parameter value.     
+    **/
     String style() default "";
 
     /**
-     *
      * When this is true, property values of type array or object generate separate parameters for each value of the array,
      * or key-value-pair of the map.
-     *
+     * For other types of properties this property has no effect. When style is form, the default value is true.
+	 * For all other styles, the default value is false.
      **/
     boolean explode() default false;
 
     /**
-     *
      * Determines whether the parameter value SHOULD allow reserved characters,
-     * as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.
-     *
+     * as defined by RFC3986 to be included without percent-encoding.
+     * @see RFC3986 for full definition of reserved characters
      **/
     boolean allowReserved() default false;
 
     /**
-     * An array of header objects
-     *
+	 * Headers property of an Encoding is a map that allows additional information to be provided as headers.
      */
     Header[] headers() default {};
 

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

@@ -210,10 +210,11 @@
   String type() default "";
 
   /**
-   * Provides a list of allowable values.  This field map to the enum property in the OAS schema.
+   * Provides a list of enum values.  This field maps to the enum property in the OAS schema
+   * and the enumeration property in the corresponding model.
    * @return a list of allowed schema values
    */
-  String[] allowableValues() default {};
+  String[] enumeration() default {};
 
   /**
    * Provides a default value.

api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthScope.java

@@ -24,6 +24,7 @@
 
 /**
  * Represents an OAuth scope.
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#oauthFlowsObject" 
  **/
 @Target({  })
 @Retention(RetentionPolicy.RUNTIME)

api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirement.java

@@ -37,7 +37,8 @@
     String name();
 
     /**
-     * If the security scheme is of type "oauth2" or "openIdConnect", then the value is a list of scope names required for the execution.  For other security scheme types, the array must be empty.
+     * If the security scheme is of type "oauth2" or "openIdConnect", then the value is a list of scope names required for the execution.  
+     * For other security scheme types, the array MUST be empty.
      */
     String[] scopes() default {};
 }

api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityScheme.java

@@ -25,14 +25,17 @@
 
 
 /**
- * Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter), OAuth2's common flows (implicit, password, application and access code) as defined in RFC6749, and OpenID Connect Discovery.
+ * Defines a security scheme that can be used by the operations. 
+ * Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter), OAuth2's common flows (implicit, password, application and access code) as defined in RFC6749, and OpenID Connect Discovery.
  **/
 @Target({ ElementType.METHOD,
         ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
 public @interface SecurityScheme {
   /**
+   * Type is a REQUIRED property that specifies the type of SecurityScheme instance.
+	 * <p>
    * The type of the security scheme. Valid values are "apiKey", "http", "oauth2", "openIdConnect".
    **/
   String type();
@@ -43,33 +46,40 @@
   String description() default "";
 
   /**
-   * The name of the header or query parameter to be used. Applies to apiKey type.
+   * Name is a REQUIRED property for apiKey type. It is the name of the header, query or cookie parameter to be used.
+   * Applies to apiKey type.
    **/
   String name() default "";
 
   /**
-   * The location of the API key. Valid values are "query" or "header".  Applies to apiKey type.
+   * The location of the API key. Valid values are "query" or "header". 
+   * A REQUIRED property for apiKey type.
    **/
   String in() default "";
 
   /**
-   * The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC 7235.  Applies to http type.
+   * The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC 7235.  
+   * A REQUIRED property for http type.
    **/
   String scheme() default "";
 
   /**
-   * A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an
-   * authorization server, so this information is primarily for documentation purposes.  Applies to http ("bearer") type.
+   * A hint to the client to identify how the bearer token is formatted. 
+   * Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.  
+   * Applies to http ("bearer") type.
    **/
   String bearerFormat() default "";
 
   /**
-   * Required. An object containing configuration information for the flow types supported.  Applies to oauth2 type.
+   * This is a REQUIRED property for oauth2 type.
+   * An object containing configuration information for the flow types supported.  
    **/
   OAuthFlows flows() default @OAuthFlows;
 
   /**
-   * Required. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL.  Applies to openIdConnect.
+   * This is a REQUIRED property for openIdConnect type.
+   * OpenId Connect URL to discover OAuth2 configuration values. 
+   * This MUST be in the form of a URL.
    **/
   String openIdConnectUrl() default "";
 

api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Server.java

@@ -31,12 +31,16 @@
 @Inherited
 public @interface Server {
   /**
-   * Required. A URL to the target host. This URL supports Server Variables and may be relative, to indicate that the host location is relative to the location where the OpenAPI definition is being served. Variable substitutions will be made when a variable is named in {brackets}.
+   * A URL to the target host. 
+   * This URL supports Server Variables and may be relative, to indicate that the host location is relative to the location where the OpenAPI definition is being served. 
+   * Variable substitutions will be made when a variable is named in {brackets}.
+   * This is a REQUIRED property.
    **/
   String url() default "";
 
   /**
-   * An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+   * An optional string describing the host designated by the URL. 
+   * CommonMark syntax MAY be used for rich text representation.
    **/
   String description() default "";
 

api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/ServerVariable.java

@@ -30,22 +30,24 @@
 @Inherited
 public @interface ServerVariable {
   /**
-   * Required.  The name of this variable.
+   * The name of this server variable. This is a REQUIRED property.
    **/
   String name();
 
   /**
-   * An array of allowable values for this variable.  This field map to the enum property in the OAS schema.
+   * An array of enum values for this variable.  This field maps to the enum property in the OAS schema
+   * and to enumeration field of ServerVariable model.
    **/
-  String[] allowableValues() default "";
+  String[] enumeration() default "";
 
   /**
-   * Required.  The default value of this variable.
+   * The default value of this server variable. This is a REQUIRED property.
    **/
   String defaultValue();
 
   /**
-   * An optional description for the server variable.
+   * An optional description for the server variable. 
+   * CommonMark syntax can be used for rich text representation.
    **/
   String description() default "";