Repository: eclipse/microprofile-open-api
Pull request #325 (2019-01-03 16:10:15)

Merge master into 2.0
See #323, but other changes made on `master` are also relevant for this PR.


Patch:
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java b/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java
index 0c5e52a..77d8751 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java
@@ -355,7 +355,9 @@ public final class OASFactory {
      * This method creates a new {@link org.eclipse.microprofile.openapi.models.servers.ServerVariables} instance.
      *
      * @return a new ServerVariables instance
+     * @deprecated since 1.1, use <code>Map&lt;String, ServerVariable&gt;</code> for server variables instead
      */
+    @Deprecated
     public static ServerVariables createServerVariables() {
         return createObject(ServerVariables.class);
     }
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/extensions/Extension.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/extensions/Extension.java
index a07c1f5..94b18a8 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/extensions/Extension.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/extensions/Extension.java
@@ -24,8 +24,7 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * An optionally named list of extension properties.
- *
+ * A named extension that should be added to the OpenAPI definition.
  */
 @Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)
@@ -33,7 +32,7 @@ import java.lang.annotation.Target;
 public @interface Extension {
 
     /**
-     * An option name for these extensions.
+     * A name for the extension.
      *
      * @return an option name for these extensions - will be prefixed with "x-"
      */
@@ -41,8 +40,23 @@ public @interface Extension {
 
     /**
      * The extension value.
-     * If the value allows parsing into an object or array, it should be converted from a string
+     * If the value should be parsed into an object or array, then the value should be stringified JSON
+     * suitable for parsing by a standard JSON parser.
      * @return the actual extension value
      */
     String value();
+
+    /**
+     * Should the value be parsed into an object/array or other simple type (number, boolean, etc) or
+     * left as a simple String.  If this is true, then the value must be parseable as one of:
+     * <ul>
+     *   <li>JSON object</li>
+     *   <li>JSON array</li>
+     *   <li>number</li>
+     *   <li>boolean</li>
+     * </ul>
+     * 
+     * @return true if the value should be parsed
+     */
+    boolean parseValue() default false;
 }
\ No newline at end of file
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 0bbb7cd..fb5c384 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
@@ -80,7 +80,7 @@ public interface Components extends Constructible, Extensible<Components> {
      * Adds the given schema to this Components' list of schemas with the given string as its key.
      *
      * @param key a key conforming to the format required for this object
-     * @param schema a reusable schema object
+     * @param schema a reusable schema object. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current Components object
      */
     Components addSchema(String key, Schema schema);
@@ -121,7 +121,7 @@ public interface Components extends Constructible, Extensible<Components> {
      * Adds the given response to this Components' map of responses with the given string as its key.
      *
      * @param key a key conforming to the format required for this object
-     * @param response a reusable response object
+     * @param response a reusable response object. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current Components object
      */
     Components addResponse(String key, APIResponse response);
@@ -162,7 +162,7 @@ public interface Components extends Constructible, Extensible<Components> {
      * Adds the given parameter to this Components' map of parameters with the given string as its key.
      *
      * @param key a key conforming to the format required for this object
-     * @param parameter a reusable parameter object
+     * @param parameter a reusable parameter object. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current Components object
      */
     Components addParameter(String key, Parameter parameter);
@@ -203,7 +203,7 @@ public interface Components extends Constructible, Extensible<Components> {
      * Adds the given example to this Components' map of examples with the given string as its key.
      *
      * @param key a key conforming to the format required for this object
-     * @param example a reusable example object
+     * @param example a reusable example object. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current Components object
      */
     Components addExample(String key, Example example);
@@ -244,7 +244,7 @@ public interface Components extends Constructible, Extensible<Components> {
      * Adds the given request body to this Components' map of request bodies with the given string as its key.
      *
      * @param key a key conforming to the format required for this object
-     * @param requestBody a reusable request body object
+     * @param requestBody a reusable request body object. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current Components object
      */
     Components addRequestBody(String key, RequestBody requestBody);
@@ -285,7 +285,7 @@ public interface Components extends Constructible, Extensible<Components> {
      * Adds the given header to this Components' map of headers with the given string as its key.
      *
      * @param key a key conforming to the format required for this object
-     * @param header a reusable header object
+     * @param header a reusable header object. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current Components object
      */
     Components addHeader(String key, Header header);
@@ -326,7 +326,7 @@ public interface Components extends Constructible, Extensible<Components> {
      * Adds the given security scheme to this Components' map of security schemes with the given string as its key.
      *
      * @param key a key conforming to the format required for this object
-     * @param securityScheme a reusable security scheme object
+     * @param securityScheme a reusable security scheme object. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current Components object
      */
     Components addSecurityScheme(String key, SecurityScheme securityScheme);
@@ -367,7 +367,7 @@ public interface Components extends Constructible, Extensible<Components> {
      * Adds the given link to this Components' map of links with the given string as its key.
      *
      * @param key a key conforming to the format required for this object
-     * @param link a reusable link object
+     * @param link a reusable link object. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current Components object
      */
     Components addLink(String key, Link link);
@@ -408,7 +408,7 @@ public interface Components extends Constructible, Extensible<Components> {
      * Adds the given callback to this Components' map of callbacks with the given string as its key.
      *
      * @param key a key conforming to the format required for this object
-     * @param callback a reusable callback object
+     * @param callback a reusable callback object. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current Components object
      */
     Components addCallback(String key, Callback callback);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/Extensible.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/Extensible.java
index 9bbc84f..155cef5 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/Extensible.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Extensible.java
@@ -51,7 +51,7 @@ public interface Extensible<T extends Extensible<T>> {
      * Adds the given object to this Extensible's map of extensions, with the given name as its key.
      *
      * @param name the key used to access the extension object. Always prefixed by "x-".
-     * @param value data not required by the specification
+     * @param value data not required by the specification. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current instance
      */
     T addExtension(String name, Object value);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/Operation.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/Operation.java
index 892d02c..805d0a2 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/Operation.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Operation.java
@@ -297,7 +297,8 @@ public interface Operation extends Constructible, Extensible<Operation> {
      * Adds the given callback item to this Operation's map of callbacks.
      *
      * @param key a key conforming to the format required for this object
-     * @param callback a callback that is applicable for this operation
+     * @param callback a callback that is applicable for this operation. null values will be rejected (implementation will throw an exception) or
+     *                 ignored.
      * @return the current Operation object
      **/
     Operation addCallback(String key, Callback callback);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/Paths.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/Paths.java
index 552d24d..9d3c10c 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/Paths.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Paths.java
@@ -35,7 +35,7 @@ public interface Paths extends Constructible, Extensible<Paths> {
      * Adds the given path item to this Paths and return this instance of Paths
      * 
      * @param name a path name in the format valid for a Paths object. The field name MUST begin with a slash.
-     * @param item the path item added to the list of paths
+     * @param item the path item added to the list of paths. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current Paths instance
      */
     Paths addPathItem(String name, PathItem item);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/callbacks/Callback.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/callbacks/Callback.java
index 2931fb2..9e05989 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/callbacks/Callback.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/callbacks/Callback.java
@@ -43,7 +43,8 @@ public interface Callback extends Constructible, Extensible<Callback>, Reference
      * complete HTTP message can be accessed. This includes accessing any part of a body that a JSON Pointer RFC6901 can reference.
      * 
      * @param name a runtime expression that can be evaluated in the context of a runtime HTTP request/response
-     * @param pathItem a path to add to this Callback's list of PathItems
+     * @param pathItem a path to add to this Callback's list of PathItems. null values will be rejected (implementation will throw an exception) or
+     *                 ignored.
      * @return the current Callback instance
      */
     Callback addPathItem(String name, PathItem pathItem);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/headers/Header.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/headers/Header.java
index b4e4522..b189f16 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/headers/Header.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/headers/Header.java
@@ -261,7 +261,7 @@ public interface Header extends Constructible, Extensible<Header>, Reference<Hea
      * specified in the parameter encoding.
      *
      * @param key string to represent the example
-     * @param example example of the header
+     * @param example example of the header. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current Header instance
      */
     Header addExample(String key, Example example);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/links/Link.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/links/Link.java
index e8afeca..0aa902a 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/links/Link.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/links/Link.java
@@ -173,7 +173,8 @@ public interface Link extends Constructible, Extensible<Link>, Reference<Link> {
      *
      * @param name The name of the parameter. Can be qualified using the parameter location [{in}.]{name} for operations that use the same parameter
      *            name in different locations (e.g. path.id).
-     * @param parameter a constant or an expression to be evaluated at runtime and passed to the linked operation
+     * @param parameter a constant or an expression to be evaluated at runtime and passed to the linked operation. null values will be rejected
+     *                  (implementation will throw an exception) or ignored.
      * @return the current Link instance
      */
     Link addParameter(String name, Object parameter);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Content.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Content.java
index e20a62c..f29e80d 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Content.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Content.java
@@ -34,7 +34,8 @@ public interface Content extends Constructible {
      * into or returned from an operation.
      *
      * @param name the name of a media type e.g. application/json.
-     * @param mediaType an object that describes the content passed into or returned from an operation.
+     * @param mediaType an object that describes the content passed into or returned from an operation. null values will be rejected (implementation
+     *                  will throw an exception) or ignored.
      * @return the current Content instance
      */
     Content addMediaType(String name, MediaType mediaType);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Discriminator.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Discriminator.java
index 774b083..bdfa4ec 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Discriminator.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Discriminator.java
@@ -63,7 +63,7 @@ public interface Discriminator extends Constructible {
      * Maps the given name to the given value and stores it in this Discriminator's mapping property.
      * 
      * @param name a key which will be compared to information from a request body or response payload.
-     * @param value a schema name or reference
+     * @param value a schema name or reference. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current Discriminator instance
      */
     Discriminator addMapping(String name, String value);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Encoding.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Encoding.java
index 9915c2b..bbc3fb1 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Encoding.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Encoding.java
@@ -114,7 +114,7 @@ public interface Encoding extends Constructible, Extensible<Encoding> {
      * Adds the given header to this Encoding' list of headers with the given string as its key.
      *
      * @param key a key conforming to the format required for this object
-     * @param header the header object
+     * @param header the header object. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current Encoding object
      */
     Encoding addHeader(String key, Header header);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MediaType.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MediaType.java
index e67f25c..4ad65ee 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MediaType.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MediaType.java
@@ -91,7 +91,7 @@ public interface MediaType extends Constructible, Extensible<MediaType> {
      * present.
      *
      * @param key any unique name to identify the example object
-     * @param example an example of a media type
+     * @param example an example of a media type. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current MediaType instance
      */
     MediaType addExample(String key, Example example);
@@ -160,7 +160,8 @@ public interface MediaType extends Constructible, Extensible<MediaType> {
      * Adds an Encoding item to the encoding property of a MediaType instance.
      *
      * @param key a property name in the schema
-     * @param encodingItem an encoding definition to apply to the schema property.
+     * @param encodingItem an encoding definition to apply to the schema property. null values will be rejected (implementation will throw an
+     *                     exception) or ignored.
      * @return the current MediaType instance
      */
     MediaType addEncoding(String key, Encoding encodingItem);
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 9f85cef..af084db 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
@@ -630,7 +630,8 @@ public interface Schema extends Extensible<Schema>, Constructible, Reference<Sch
      * Adds a Schema property of the provided name using the given schema.
      *
      * @param key the name of a new Schema property
-     * @param propertySchema the Schema which describes the properties of the named property
+     * @param propertySchema the Schema which describes the properties of the named property. null values will be rejected (implementation will throw
+     *                       an exception) or ignored.
      * @return the current Schema instance
      */
     Schema addProperty(String key, Schema propertySchema);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/Parameter.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/Parameter.java
index 1572313..c6aabe1 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/Parameter.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/Parameter.java
@@ -371,7 +371,7 @@ public interface Parameter extends Constructible, Extensible<Parameter>, Referen
      * parameter encoding.
      *
      * @param key string to represent the example
-     * @param example example of the parameter
+     * @param example example of the parameter. null values will be rejected (implementation will throw an exception) or ignored.
      * @return the current Parameter instance
      */
     Parameter addExample(String key, Example example);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponse.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponse.java
index 844d456..4769761 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponse.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponse.java
@@ -96,7 +96,7 @@ public interface APIResponse extends Constructible, Extensible<APIResponse>, Ref
      * ApiResponse instance does not have any headers, a new map is created and the given header is added.
      *
      * @param name the unique name of the header
-     * @param header a header for the response
+     * @param header a header for the response. null values will be rejected (implementation will throw an exception) or ignored.
      * @return this ApiResponse instance
      */
 
@@ -171,7 +171,8 @@ public interface APIResponse extends Constructible, Extensible<APIResponse>, Ref
      * Adds a link to this instance of ApiResponse using the given name and Link, and returns this ApiResponse instance.
      *
      * @param name the short name of the link
-     * @param link the operation link that can be followed from the response
+     * @param link the operation link that can be followed from the response. null values will be rejected (implementation will throw an exception)
+     *             or ignored.
      * @return this ApiResponse instance
      */
 
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponses.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponses.java
index 4cdc017..add6101 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponses.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponses.java
@@ -36,7 +36,8 @@ public interface APIResponses extends Constructible, Extensible<APIResponses> {
      * Adds an APIResponse in the format of the name as a key and the item as the value to APIResponses map
      * 
      * @param name the name of APIResponse (http status code eventually with wildcard or {@value #DEFAULT})
-     * @param apiResponse the APIResponse object to be added to APIResponses map
+     * @param apiResponse the APIResponse object to be added to APIResponses map. null values will be rejected (implementation will throw an
+     *                    exception) or ignored.
      * @return APIResponses map with the added ApiResponse instance
      **/
     APIResponses addAPIResponse(String name, APIResponse apiResponse);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/Scopes.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/Scopes.java
index 5d2ffb5..bb7993b 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/Scopes.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/Scopes.java
@@ -34,7 +34,7 @@ public interface Scopes extends Constructible, Extensible<Scopes> {
      * Adds name of an existing scope object and item parameters to a Scopes instance as a key-value pair in a map.
      *
      * @param scope the name of a scope
-     * @param description description of the scope
+     * @param description description of the scope.
      * @return Scopes instance with the added key-value pair
      */
     Scopes addScope(String scope, String description);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityRequirement.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityRequirement.java
index 88f0fc5..2edabb8 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityRequirement.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityRequirement.java
@@ -34,7 +34,8 @@ public interface SecurityRequirement extends Constructible {
      * required scope (optional) provided.
      * 
      * @param securitySchemeName the name of security scheme declared in the Components section of the OpenAPI document
-     * @param scope a required scope - only valid when the defined scheme is 'oauth2' or 'openIdConnect'
+     * @param scope a required scope - only valid when the defined scheme's type is 'oauth2' or 'openIdConnect'. passing null will
+     *              result in an empty list of scopes
      * @return Updated SecurityRequirement instance
      */
     SecurityRequirement addScheme(String securitySchemeName, String scope);
@@ -44,7 +45,8 @@ public interface SecurityRequirement extends Constructible {
      * required scopes (optional) provided.
      * 
      * @param securitySchemeName the name of security scheme declared in the Components section of the OpenAPI document
-     * @param scopes the scopes required - only valid when the defined scheme is 'oauth2' or 'openIdConnect'
+     * @param scopes the scopes required - only valid when the defined scheme is 'oauth2' or 'openIdConnect'. passing null
+     *               will result in an empty list of scopes
      * @return Updated SecurityRequirement instance
      */
     SecurityRequirement addScheme(String securitySchemeName, List<String> scopes);
@@ -96,10 +98,10 @@ public interface SecurityRequirement extends Constructible {
     }
 
     /**
-     * Returns a path item for a given name. This is a convenience method for <code>getSchemes().get(name)</code>
+     * Returns a list of scopes for a given scheme name. This is a convenience method for <code>getSchemes().get(name)</code>
      * 
      * @param securitySchemeName the name of security scheme
-     * @return the corresponding path item or null.
+     * @return a list of scopes or null.
      */
     default List<String> getScheme(String securitySchemeName) {
         Map<String, List<String>> map = getSchemes();
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/Server.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/Server.java
index 3d29413..99df2ca 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/Server.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/Server.java
@@ -17,6 +17,8 @@
 
 package org.eclipse.microprofile.openapi.models.servers;
 
+import java.util.Map;
+
 import org.eclipse.microprofile.openapi.models.Constructible;
 import org.eclipse.microprofile.openapi.models.Extensible;
 
@@ -107,7 +109,7 @@ public interface Server extends Constructible, Extensible<Server> {
      * <p>
      * Variables are represented as a map between variable name and its value. The value is used for substitution in the server's URL template.
      * </p> 
-     * @return ServerVariables variables
+     * @return ServerVariables variables (in the future this method will instead return a <code>Map&lt;String, ServerVariable&gt;</code>).
      **/
     ServerVariables getVariables();
 
@@ -117,9 +119,20 @@ public interface Server extends Constructible, Extensible<Server> {
      * Variables property is a map between variable name and its value. The value is used for substitution in the server's URL template.
      * </p>
      * @param variables a map between variable name and its value
+     * @deprecated since 1.1, use {@link #setVariables(Map)} instead
      */
+    @Deprecated
     void setVariables(ServerVariables variables);
-
+    
+    /**
+     * This method sets the variables property of Server instance to the given variables argument.
+     * <p>
+     * Variables property is a map between variable name and its value. The value is used for substitution in the server's URL template.
+     * </p>
+     * @param variables a map between variable name and its value
+     */
+    void setVariables(Map<String, ServerVariable> variables);
+    
     /**
      * This method sets the variables property of Server instance to the given variables argument and returns the modified instance.
      * <p>
@@ -127,10 +140,24 @@ public interface Server extends Constructible, Extensible<Server> {
      * </p>
      * @param variables a map between variable name and its value
      * @return Server instance with the set variables property.
+     * @deprecated since 1.1, use {@link #variables(Map)} instead
      */
+    @Deprecated
     default Server variables(ServerVariables variables) {
         setVariables(variables);
         return this;
     }
 
+    /**
+     * This method sets the variables property of Server instance to the given variables argument and returns the modified instance.
+     * <p>
+     * Variables property is a map between variable name and its value. The value is used for substitution in the server's URL template.
+     * </p>
+     * @param variables a map between variable name and its value
+     * @return Server instance with the set variables property.
+     */
+    default Server variables(Map<String, ServerVariable> variables) {
+        setVariables(variables);
+        return this;
+    }
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariables.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariables.java
index c9fd6af..ccfe9c9 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariables.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariables.java
@@ -26,14 +26,17 @@ import org.eclipse.microprofile.openapi.models.Extensible;
  * ServerVariables
  *
  * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#server-variable-object">ServerVariable Object</a>
+ * @deprecated since 1.1, a future version will remove this and replace it with a <code>Map&lt;String, ServerVariable&gt;</code>, because it does not
+ * need to be extensible
  */
+@Deprecated
 public interface ServerVariables extends Constructible, Extensible<ServerVariables> {
 
     /**
      * This method adds a key-value item to a ServerVariables instance from the name-item parameter pair and returns the modified instance.
      *
      * @param name the name of ServerVariable instance
-     * @param serverVariable the ServerVariable instance
+     * @param serverVariable the ServerVariable instance. null values will be rejected (implementation will throw an exception) or ignored.
      * @return ServerVariables instance with the added name-item pair.
      */
     ServerVariables addServerVariable(String name, ServerVariable serverVariable);
diff --git a/pom.xml b/pom.xml
index 2f1ef54..9f84966 100644
--- a/pom.xml
+++ b/pom.xml
@@ -49,6 +49,7 @@
         <servlet.version>3.1.0</servlet.version>
         <httpclient.version>4.5.2</httpclient.version>
         <jackson.version>2.9.3</jackson.version>
+        <restclient.version>1.1</restclient.version>
 
         <!-- Versions of SPEC dependencies  -->
         <asciidoctor-maven.version>1.5.5</asciidoctor-maven.version>
diff --git a/spec/src/main/asciidoc/microprofile-openapi-spec.adoc b/spec/src/main/asciidoc/microprofile-openapi-spec.adoc
index 447476c..4a1b99b 100644
--- a/spec/src/main/asciidoc/microprofile-openapi-spec.adoc
+++ b/spec/src/main/asciidoc/microprofile-openapi-spec.adoc
@@ -708,6 +708,18 @@ the `/openapi` endpoint are expected to be the logical union of all the applicat
 in the runtime, which would imply merging multiple OpenAPI documents into a single
 valid document (handling conflicting IDs and unique names).
 
+== Integration with other MicroProfile specifications
+
+This section will outline specific integrations between MicroProfile OpenAPI and other MicroProfile specifications.
+
+=== MicroProfile Rest Client
+
+It is common that a microservice (A) using MicroProfile OpenAPI will also use https://github.com/eclipse/microprofile-rest-client[MicroProfile Rest Client]
+to make outbound calls into another microservice (B).  In this case, we do not want
+the interface for microservice (B) to appear in microservice (A)'s OAS3 document.
+
+Therefore, vendors are required to exclude from the final OAS3 document any interface annotated with https://github.com/eclipse/microprofile-rest-client/blob/master/api/src/main/java/org/eclipse/microprofile/rest/client/inject/RegisterRestClient.java[org.eclipse.microprofile.rest.client.inject.RegisterRestClient].
+
 == Exposing platform OpenAPIs
 
 Vendors are required to support a mechanism to expose `platform` OpenAPIs to consumers. 
diff --git a/tck/pom.xml b/tck/pom.xml
index 40d205b..2bac47a 100644
--- a/tck/pom.xml
+++ b/tck/pom.xml
@@ -86,7 +86,14 @@
             <version>${project.version}</version>
             <scope>provided</scope>
         </dependency>
-
+        
+        <dependency>
+            <groupId>org.eclipse.microprofile.rest.client</groupId>
+            <artifactId>microprofile-rest-client-api</artifactId>
+            <version>${restclient.version}</version>
+            <scope>provided</scope>
+        </dependency>
+        
         <dependency>
             <groupId>org.testng</groupId>
             <artifactId>testng</artifactId>
@@ -96,7 +103,6 @@
         <dependency>
             <groupId>org.jboss.arquillian.testng</groupId>
             <artifactId>arquillian-testng-container</artifactId>
-            <version>${arquillian.version}</version>
         </dependency>
 
         <dependency>
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AirlinesResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AirlinesResource.java
index 70faef4..ed8fcae 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AirlinesResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AirlinesResource.java
@@ -30,7 +30,8 @@ import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
 import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 import org.eclipse.microprofile.openapi.annotations.tags.Tags;
 import org.eclipse.microprofile.openapi.annotations.enums.SchemaType;
-
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
+import org.eclipse.microprofile.openapi.annotations.extensions.Extensions;
 import org.eclipse.microprofile.openapi.apps.airlines.JAXRSApp;
 import org.eclipse.microprofile.openapi.apps.airlines.model.Airline;
 import org.eclipse.microprofile.openapi.apps.airlines.model.Flight;
@@ -96,6 +97,17 @@ public class AirlinesResource {
         summary = "Retrieve all available airlines",
         operationId = "getAirlines")
     @Produces("application/json")
+    @Extensions({
+        @Extension(name = "x-string-property", value = "string-value"),
+        @Extension(name = "x-boolean-property", value = "true", parseValue = true),
+        @Extension(name = "x-number-property", value = "117", parseValue = true),
+        @Extension(
+            name = "x-object-property", 
+            value = "{ \"property-1\" : \"value-1\", \"property-2\" : \"value-2\", \"property-3\" : { \"prop-3-1\" : 17, \"prop-3-2\" : true } }", 
+            parseValue = true),
+        @Extension(name = "x-string-array-property", value = "[ \"one\", \"two\", \"three\" ]", parseValue = true),
+        @Extension(name = "x-object-array-property", value = "[ { \"name\": \"item-1\" }, { \"name\" : \"item-2\" } ]", parseValue = true)
+    })
     public Response getAirlines(){
         return Response.ok().entity(airlines.values()).build();
     }
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/PlayerService.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/PlayerService.java
new file mode 100644
index 0000000..71f6f49
--- /dev/null
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/PlayerService.java
@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2018 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.apps.airlines.resources;
+
+import javax.ws.rs.GET;
+import javax.ws.rs.HeaderParam;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.MediaType;
+
+import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
+
+
+@RegisterRestClient
+@Path("/")
+public interface PlayerService {
+
+    @GET
+    @Path("/player/{playerId}")
+    @Produces(MediaType.APPLICATION_JSON)
+    public String getPlayerById(@PathParam("playerId") String id);
+
+    @POST
+    @Path("/rank/{playerId}/recordGame")
+    public void recordGame(@PathParam("playerId") String id, @QueryParam("place") int place, @HeaderParam("Authorization") String token);
+
+}
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/ReviewResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/ReviewResource.java
index 5e208e8..6847393 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/ReviewResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/ReviewResource.java
@@ -84,11 +84,19 @@ import org.eclipse.microprofile.openapi.apps.airlines.model.User;
         ),
         authorizationCode = @OAuthFlow(
             authorizationUrl = "https://example.com/api/oauth/dialog",
-            tokenUrl = "https://example.com/api/oauth/token"
+            tokenUrl = "https://example.com/api/oauth/token",
+            scopes = @OAuthScope(
+                name = "read:reviews",
+                description = "search for a review"
+            )
         ),
         password = @OAuthFlow(
             refreshUrl = "https://example.com/api/oauth/refresh",
-            tokenUrl = "https://example.com/api/oauth/token"
+            tokenUrl = "https://example.com/api/oauth/token",
+            scopes = @OAuthScope(
+                name = "write:reviews",
+                description = "create a review"
+            )
         ),
         clientCredentials = @OAuthFlow(
             tokenUrl = "https://example.com/api/oauth/token",
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/UserResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/UserResource.java
index 92b6aea..f30bf86 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/UserResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/UserResource.java
@@ -451,10 +451,12 @@ public class UserResource {
     })
     @Operation(
         summary = "Get user by user name",
-        operationId = "getUserByUserName")
+        operationId = "getUserByName")
     public Response getUserByName(
         @Parameter(
-            ref= "username"
+            name = "username",
+            schema = @Schema(type = SchemaType.STRING),
+            required = true
             )
         @PathParam("username") String userName) throws ApiException {
             User user = userData.findUserByName(userName);


Test patch:
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/AirlinesAppTest.java b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/AirlinesAppTest.java
index dbfea64..37314ce 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/AirlinesAppTest.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/AirlinesAppTest.java
@@ -182,6 +182,14 @@ public class AirlinesAppTest extends AppTestBase {
         vr.body("paths.'/availability'.get.summary", equalTo("Retrieve all available flights"));
         vr.body("paths.'/availability'.get.operationId", equalTo("getFlights"));
     }
+    
+    @RunAsClient
+    @Test(dataProvider = "formatProvider")
+    public void testRestClientNotPickedUp(String type) {
+        ValidatableResponse vr = callEndpoint(type);
+        //We should not be picking up interfaces annotated with @RegisterRestClient
+        vr.body("paths.'/player/{playerId}'", equalTo(null));
+    }
 
     @RunAsClient
     @Test(dataProvider = "formatProvider")
@@ -253,7 +261,7 @@ public class AirlinesAppTest extends AppTestBase {
         vr.body("paths.'/user/{username}'.delete.operationId", equalTo("deleteUser"));
 
         vr.body("paths.'/user/{username}'.get.summary", equalTo("Get user by user name"));
-        vr.body("paths.'/user/{username}'.get.operationId", equalTo("getUserByUserName"));
+        vr.body("paths.'/user/{username}'.get.operationId", equalTo("getUserByName"));
 
         vr.body("paths.'/user/{id}'.get.summary", equalTo("Get user by id"));
         vr.body("paths.'/user/{id}'.get.operationId", equalTo("getUserById"));
@@ -916,4 +924,19 @@ public class AirlinesAppTest extends AppTestBase {
                 both(containsString("Your server should return this HTTP status code if no longer interested")).
                 and(containsString("in further updates")));
     }
+
+    @RunAsClient
+    @Test(dataProvider = "formatProvider")
+    public void testExtensionParsing(String type) {
+        ValidatableResponse vr = callEndpoint(type);
+
+        vr.body("paths.'/'.get.'x-string-property'", equalTo("string-value"));
+        vr.body("paths.'/'.get.'x-boolean-property'", equalTo(Boolean.TRUE));
+        vr.body("paths.'/'.get.'x-number-property'", equalTo(117));
+        vr.body("paths.'/'.get.'x-object-property'.'property-1'", equalTo("value-1"));
+        vr.body("paths.'/'.get.'x-object-property'.'property-3'.'prop-3-1'", equalTo(17));
+        vr.body("paths.'/'.get.'x-string-array-property'[1]", equalTo("two"));
+        vr.body("paths.'/'.get.'x-object-array-property'[1].name", equalTo("item-2"));
+    }
+
 }
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java
index b044da5..dfb3e20 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java
@@ -36,7 +36,9 @@ import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.function.BiFunction;
 import java.util.function.Function;
+import java.util.function.Supplier;
 
 import org.eclipse.microprofile.openapi.OASFactory;
 import org.eclipse.microprofile.openapi.models.Components;
@@ -174,6 +176,7 @@ public class ModelConstructionTest {
         
         Callback otherCallbackValue  = createConstructibleInstance(Callback.class);
         checkMapImmutable(c, Components::getCallbacks, "otherCallback", otherCallbackValue);
+        checkNullValueInAdd(c::getCallbacks, c::addCallback, "someCallback", callbackValue);
         
         final String exampleKey = "myExample";
         final Example exampleValue = createConstructibleInstance(Example.class);
@@ -194,6 +197,7 @@ public class ModelConstructionTest {
         assertEquals(c.getExamples().size(), 2, "The map is expected to contain two entries.");
         
         checkMapImmutable(c, Components::getExamples, "otherExample", otherExampleValue);
+        checkNullValueInAdd(c::getExamples, c::addExample, "someExample", exampleValue);
         
         final String headerKey = "myHeader";
         final Header headerValue = createConstructibleInstance(Header.class);
@@ -214,6 +218,7 @@ public class ModelConstructionTest {
         assertEquals(c.getHeaders().size(), 2, "The map is expected to contain two entries.");
         
         checkMapImmutable(c, Components::getHeaders, "otherHeader", otherHeaderValue);
+        checkNullValueInAdd(c::getHeaders, c::addHeader, "some-header", headerValue);
         
         final String linkKey = "myLink";
         final Link linkValue = createConstructibleInstance(Link.class);
@@ -234,6 +239,7 @@ public class ModelConstructionTest {
         assertEquals(c.getLinks().size(), 2, "The map is expected to contain two entries.");
         
         checkMapImmutable(c, Components::getLinks, "otherLink", otherLinkValue);
+        checkNullValueInAdd(c::getLinks, c::addLink, "someLink", linkValue);
         
         final String parameterKey = "myParameter";
         final Parameter parameterValue = createConstructibleInstance(Parameter.class);
@@ -242,6 +248,7 @@ public class ModelConstructionTest {
         assertEquals(c.getParameters().size(), 1, "The list is expected to contain one entry.");
         c.removeParameter(parameterKey);
         assertEquals(c.getParameters().size(), 0, "The list is expected to be empty.");
+        checkNullValueInAdd(c::getParameters, c::addParameter, "someParameter", parameterValue);
         
         final String parameterKey2 = "myParameterKey2";
         final Parameter parameterValue2 = createConstructibleInstance(Parameter.class);
@@ -274,6 +281,7 @@ public class ModelConstructionTest {
         
         RequestBody otherRequestBodyValue  = createConstructibleInstance(RequestBody.class);
         checkMapImmutable(c, Components::getRequestBodies, "otherRequestBody", otherRequestBodyValue);
+        checkNullValueInAdd(c::getRequestBodies, c::addRequestBody, "someRequestBody", requestBodyValue);
         
         final String responseKey = "myResponse";
         final APIResponse responseValue = createConstructibleInstance(APIResponse.class);
@@ -294,6 +302,7 @@ public class ModelConstructionTest {
         
         APIResponse otherAPIResponseValue  = createConstructibleInstance(APIResponse.class);
         checkMapImmutable(c, Components::getResponses, "otherAPIResponse", otherAPIResponseValue);
+        checkNullValueInAdd(c::getResponses, c::addResponse, "someResponse", responseValue);
         
         final String schemaKey = "mySchema";
         final Schema schemaValue = createConstructibleInstance(Schema.class);
@@ -314,6 +323,7 @@ public class ModelConstructionTest {
         
         Schema otherSchemaValue  = createConstructibleInstance(Schema.class);
         checkMapImmutable(c, Components::getSchemas, "otherSchema", otherSchemaValue);
+        checkNullValueInAdd(c::getSchemas, c::addSchema, "someSchema", schemaValue);
         
         final String securitySchemeKey = "mySecurityScheme";
         final SecurityScheme securitySchemeValue = createConstructibleInstance(SecurityScheme.class);
@@ -334,6 +344,7 @@ public class ModelConstructionTest {
         
         SecurityScheme otherSecuritySchemeValue  = createConstructibleInstance(SecurityScheme.class);
         checkMapImmutable(c, Components::getSecuritySchemes, "otherSecurityScheme", otherSecuritySchemeValue);
+        checkNullValueInAdd(c::getSecuritySchemes, c::addSecurityScheme, "someSecurityScheme", securitySchemeValue);
     }
     
     @Test
@@ -501,6 +512,7 @@ public class ModelConstructionTest {
         
         Callback otherCallback  = createConstructibleInstance(Callback.class);
         checkMapImmutable(o, Operation::getCallbacks, "otherCallback", otherCallback);
+        checkNullValueInAdd(o::getCallbacks, o::addCallback, "someCallback", callbackValue);
     }
     
     @Test
@@ -618,6 +630,7 @@ public class ModelConstructionTest {
         
         final PathItem otherValue = createConstructibleInstance(PathItem.class);
         checkMapImmutable(p, Paths::getPathItems, "/otherPathItem", otherValue);
+        checkNullValueInAdd(p::getPathItems, p::addPathItem, "/other", otherValue);
     }
     
     @Test
@@ -653,6 +666,7 @@ public class ModelConstructionTest {
         
         final PathItem otherValue = createConstructibleInstance(PathItem.class);
         checkMapImmutable(c, Callback::getPathItems, "otherPathItem", otherValue);
+        checkNullValueInAdd(c::getPathItems, c::addPathItem, "other", otherValue);
     }
     
     @Test
@@ -683,6 +697,7 @@ public class ModelConstructionTest {
         
         Example otherExampleValue = createConstructibleInstance(Example.class);
         checkMapImmutable(h, Header::getExamples, "otherExample", otherExampleValue);
+        checkNullValueInAdd(h::getExamples, h::addExample, "otherExample", exampleValue);
     }
     
     @Test
@@ -723,6 +738,7 @@ public class ModelConstructionTest {
         
         Object otherExampleValue = new Object();
         checkMapImmutable(l, Link::getParameters, "otherParameter", otherExampleValue);
+        checkNullValueInAdd(l::getParameters, l::addParameter, "otherParameter", parameterValue);
     }
     
     @Test
@@ -783,6 +799,7 @@ public class ModelConstructionTest {
         
         final String otherValue = new String("otherValue");
         checkMapImmutable(d, Discriminator::getMapping, "otherValue", otherValue);
+        checkNullValueInAdd(d::getMapping, d::addMapping, "otherKey", value);
     }
     
     @Test
@@ -808,6 +825,7 @@ public class ModelConstructionTest {
         
         final Header otherHeaderValue = createConstructibleInstance(Header.class);
         checkMapImmutable(e, Encoding::getHeaders, "otherHeader", otherHeaderValue);
+        checkNullValueInAdd(e::getHeaders, e::addHeader, "otherHeaderKey", headerValue);
     }
     
     @Test
@@ -833,6 +851,7 @@ public class ModelConstructionTest {
         
         Encoding otherEncodingValue = createConstructibleInstance(Encoding.class);
         checkMapImmutable(mt, MediaType::getEncoding, "otherEncoding", otherEncodingValue);
+        checkNullValueInAdd(mt::getEncoding, mt::addEncoding, "otherEncoding", encodingValue);
         
         final String exampleKey = "myExample";
         final Example exampleValue = createConstructibleInstance(Example.class);
@@ -853,6 +872,7 @@ public class ModelConstructionTest {
         
         Example otherExampleValue = createConstructibleInstance(Example.class);
         checkMapImmutable(mt, MediaType::getExamples, "otherExample", otherExampleValue);
+        checkNullValueInAdd(mt::getExamples, mt::addExample, "otherExample", exampleValue);
     }
     
     @Test
@@ -964,6 +984,7 @@ public class ModelConstructionTest {
         
         final Schema otherPropertyValue = createConstructibleInstance(Schema.class);
         checkMapImmutable(s, Schema::getProperties, "otherPropertyKey", otherPropertyValue);
+        checkNullValueInAdd(s::getProperties, s::addProperty, "otherProperty", propertySchemaValue);
         
         final String required = new String("required");
         checkSameObject(s, s.addRequired(required));
@@ -1012,6 +1033,7 @@ public class ModelConstructionTest {
         
         Example otherExampleValue = createConstructibleInstance(Example.class);
         checkMapImmutable(p, Parameter::getExamples, "otherExample", otherExampleValue);
+        checkNullValueInAdd(p::getExamples, p::addExample, "otherExample", exampleValue);
     }
     
     @Test
@@ -1042,6 +1064,7 @@ public class ModelConstructionTest {
         
         Header otherHeaderValue  = createConstructibleInstance(Header.class);
         checkMapImmutable(response, APIResponse::getHeaders, "otherHeader", otherHeaderValue);
+        checkNullValueInAdd(response::getHeaders, response::addHeader, "some-header", headerValue);
         
         final String linkKey = "myLinkKey";
         final Link linkValue = createConstructibleInstance(Link.class);
@@ -1062,6 +1085,7 @@ public class ModelConstructionTest {
         assertEquals(response.getLinks().size(), 2, "The map is expected to contain two entries.");
         
         checkMapImmutable(response, APIResponse::getLinks, "otherLink", otherLinkValue);
+        checkNullValueInAdd(response::getLinks, response::addLink, "someLinkKey", linkValue);
     }
     
     @Test
@@ -1115,6 +1139,8 @@ public class ModelConstructionTest {
         responses.setDefaultValue(responseValue4);
         checkMapEntry(responses.getAPIResponses(), APIResponses.DEFAULT, responseValue4);
         checkSameObject(responseValue4, responses.getDefaultValue());
+        
+        checkNullValueInAdd(responses::getAPIResponses, responses::addAPIResponse, "4XX", otherValue);
     }
     
     @Test
@@ -1160,6 +1186,11 @@ public class ModelConstructionTest {
         
         final String otherValue = new String("otherDescription");
         checkMapImmutable(s, Scopes::getScopes, "otherScope", otherValue);
+        
+        String scopeKey3 = "myScope3";
+        s.addScope(scopeKey3, null);
+        assertTrue(s.hasScope(scopeKey3), "Expected " + scopeKey3 + " to be present in the map");
+        assertNull(s.getScope(scopeKey3), "Expected the value of " + scopeKey3 + " to be null.");
     }
     
     @Test
@@ -1195,6 +1226,20 @@ public class ModelConstructionTest {
         
         final List<String> otherValue = new ArrayList<String>();
         checkMapImmutable(sr, SecurityRequirement::getSchemes, "otherScheme", otherValue);
+        
+        final String schemeKey3 = "myScheme3";
+        sr.addScheme(schemeKey3, (String) null);
+        assertTrue(sr.hasScheme(schemeKey3), "Expected " + schemeKey3 + " to be present");
+        final List<String> schemeValue3 = Collections.emptyList();
+        assertEquals(sr.getScheme(schemeKey3), schemeValue3, 
+                "The value associated with the key: " + schemeKey3 + " is expected to be an empty list.");
+
+        final String schemeKey4 = "myScheme3";
+        sr.addScheme(schemeKey4, (List<String>) null);
+        assertTrue(sr.hasScheme(schemeKey4), "Expected " + schemeKey4 + " to be present");
+        final List<String> schemeValue4 = Collections.emptyList();
+        assertEquals(sr.getScheme(schemeKey4), schemeValue4, 
+                "The value associated with the key: " + schemeKey4 + " is expected to be an empty list.");
     }
     
     @Test
@@ -1204,7 +1249,17 @@ public class ModelConstructionTest {
     
     @Test
     public void serverTest() {
-        processConstructible(Server.class);
+        Server server = processConstructible(Server.class);
+        
+        final ServerVariable sv1 = createConstructibleInstance(ServerVariable.class);
+        server.setVariables(Collections.singletonMap("var1", sv1));
+        Map<String,ServerVariable> variables = server.getVariables().getServerVariables();
+        assertEquals(variables.size(), 1, "The map is expected to contain one entry.");
+        assertTrue(variables.containsKey("var1"), "The map is expected to contain a 'var1' entry.");
+        assertEquals(variables.get("var1"), sv1, "The value corresponding to the 'var1' is wrong.");
+        
+        server.setVariables((Map<String, ServerVariable>) null);
+        assertNull(server.getVariables(), "The value is expected to be null.");
     }
     
     @Test
@@ -1231,6 +1286,7 @@ public class ModelConstructionTest {
     }
     
     @Test
+    @Deprecated
     public void serverVariablesTest() {
         final ServerVariables svs = processConstructible(ServerVariables.class);
         
@@ -1263,6 +1319,7 @@ public class ModelConstructionTest {
         
         final ServerVariable otherValue = createConstructibleInstance(ServerVariable.class);
         checkMapImmutable(svs, ServerVariables::getServerVariables, "otherServerVariable", otherValue);
+        checkNullValueInAdd(svs::getServerVariables, svs::addServerVariable, "other", otherValue);
     }
     
     @Test
@@ -1569,6 +1626,30 @@ public class ModelConstructionTest {
         assertEquals(map2.size(), originalSize, "The map is expected to have a size of " + originalSize);
     }
     
+    private <O, T> void checkNullValueInAdd(Supplier<Map<String, T>> mapGetter, BiFunction<String, T, O> mapAdd, String key, T value) {
+        // add null as value for 'key'
+        try {
+            mapAdd.apply(key, null);
+        }
+        catch (Exception e) {
+            //It is allowed to throw an exception
+        }
+        assertFalse(mapGetter.get().containsKey(key), "The map is expected to not contain the key: " + key);
+        
+        // add value as value for 'key'
+        mapAdd.apply(key, value);
+        assertTrue(mapGetter.get().containsKey(key), "The map is expected to contain the key: " + key);
+        
+        // add null again as value for 'key'
+        try {
+            mapAdd.apply(key, null);
+        }
+        catch (Exception e) {
+            //It is allowed to throw an exception
+        }
+        assertTrue(mapGetter.get().containsKey(key), "The map is expected to contain the key: " + key);
+    }
+    
     private <T> void checkListEntry(List<T> list, T value) {
         assertNotNull(list, "The list must not be null.");
         assertTrue(list.stream().anyMatch((v) -> v == value), "The list is expected to contain the value: " + value);