From 4e27dbada86be4633a9c8ae37b5e74715aa8f555 Mon Sep 17 00:00:00 2001
From: Michael Glavassevich <mrglavas@ca.ibm.com>
Date: Wed, 11 Oct 2017 13:54:56 -0400
Subject: [PATCH 01/23] Adding initial set of model interfaces.

Signed-off-by: Michael Glavassevich <mrglavas@ca.ibm.com>
---
 .../openapi/models/Components.java            | 356 +++++++
 .../openapi/models/Constructible.java         |  21 +
 .../openapi/models/ExternalDocumentation.java | 100 ++
 .../microprofile/openapi/models/OpenAPI.java  | 305 ++++++
 .../openapi/models/Operation.java             | 383 +++++++
 .../microprofile/openapi/models/PathItem.java | 411 ++++++++
 .../microprofile/openapi/models/Paths.java    |  61 ++
 .../openapi/models/callbacks/Callback.java    |  63 ++
 .../models/callbacks/package-info.java        |  18 +
 .../openapi/models/examples/Example.java      | 168 +++
 .../openapi/models/examples/package-info.java |  18 +
 .../openapi/models/headers/Header.java        | 345 +++++++
 .../openapi/models/headers/package-info.java  |  18 +
 .../openapi/models/info/Contact.java          | 125 +++
 .../openapi/models/info/Info.java             | 196 ++++
 .../openapi/models/info/License.java          |  96 ++
 .../openapi/models/info/package-info.java     |  18 +
 .../openapi/models/links/Link.java            | 255 +++++
 .../openapi/models/links/LinkParameter.java   |  76 ++
 .../openapi/models/links/package-info.java    |  18 +
 .../openapi/models/media/Content.java         |  40 +
 .../openapi/models/media/Discriminator.java   |  81 ++
 .../openapi/models/media/Encoding.java        | 187 ++++
 .../openapi/models/media/MediaType.java       | 198 ++++
 .../openapi/models/media/Schema.java          | 977 ++++++++++++++++++
 .../openapi/models/media/XML.java             | 193 ++++
 .../openapi/models/media/package-info.java    |  18 +
 .../openapi/models/package-info.java          |  18 +
 .../models/parameters/CookieParameter.java    |  27 +
 .../models/parameters/HeaderParameter.java    |  27 +
 .../openapi/models/parameters/Parameter.java  | 470 +++++++++
 .../models/parameters/PathParameter.java      |  27 +
 .../models/parameters/QueryParameter.java     |  27 +
 .../models/parameters/RequestBody.java        | 167 +++
 .../models/parameters/package-info.java       |  18 +
 .../openapi/models/responses/ApiResponse.java | 214 ++++
 .../models/responses/ApiResponses.java        |  62 ++
 .../models/responses/package-info.java        |  18 +
 .../openapi/models/security/OAuthFlow.java    | 168 +++
 .../openapi/models/security/OAuthFlows.java   | 167 +++
 .../openapi/models/security/Scopes.java       |  70 ++
 .../models/security/SecurityRequirement.java  |  69 ++
 .../models/security/SecurityScheme.java       | 342 ++++++
 .../openapi/models/security/package-info.java |  18 +
 .../openapi/models/servers/Server.java        | 140 +++
 .../models/servers/ServerVariable.java        | 153 +++
 .../models/servers/ServerVariables.java       |  48 +
 .../openapi/models/servers/package-info.java  |  18 +
 .../microprofile/openapi/models/tags/Tag.java | 141 +++
 .../openapi/models/tags/package-info.java     |  18 +
 50 files changed, 7172 insertions(+)
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/Components.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/Constructible.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/Operation.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/Paths.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/callbacks/Callback.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/callbacks/package-info.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/examples/package-info.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/headers/Header.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/headers/package-info.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/info/Info.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/info/License.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/info/package-info.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/links/Link.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/links/LinkParameter.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/links/package-info.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/Content.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/Discriminator.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/Encoding.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/MediaType.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/package-info.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/package-info.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/CookieParameter.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/HeaderParameter.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/Parameter.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/PathParameter.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/QueryParameter.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/package-info.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/responses/ApiResponse.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/responses/ApiResponses.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/responses/package-info.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/security/Scopes.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityRequirement.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/security/package-info.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/servers/Server.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariables.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/servers/package-info.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/tags/package-info.java

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
new file mode 100644
index 000000000..d22edc46c
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Components.java
@@ -0,0 +1,356 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.callbacks.Callback;
+import org.eclipse.microprofile.openapi.models.examples.Example;
+import org.eclipse.microprofile.openapi.models.headers.Header;
+import org.eclipse.microprofile.openapi.models.links.Link;
+import org.eclipse.microprofile.openapi.models.media.Schema;
+import org.eclipse.microprofile.openapi.models.parameters.Parameter;
+import org.eclipse.microprofile.openapi.models.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.models.responses.ApiResponse;
+import org.eclipse.microprofile.openapi.models.security.SecurityScheme;
+
+/**
+ * Components
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#componentsObject"
+ */
+public interface Components extends Constructible {
+
+	/**
+	 * returns the schemas property from a Components instance.
+	 *
+	 * @return Map&lt;String, Schema&gt; schemas
+	 **/
+	Map<String, Schema> getSchemas();
+
+	/**
+	 * sets this Components' schemas property to the given schema.
+	 * 
+	 * @param Map&lt;String, Schema&gt;schemas
+	 */
+	void setSchemas(Map<String, Schema> schemas);
+
+	/**
+	 * sets this Components' schemas property to the given schema and returns this Components.
+	 * 
+	 * @param Map&lt;String, Schema&gt;schemas
+	 * @return Components
+	 */
+	Components schemas(Map<String, Schema> schemas);
+
+	/**
+	 * Adds the given schema to this Components list of schemas, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param Schema schemasItem
+	 * @return Components
+	 */
+	Components addSchemas(String key, Schema schemasItem);
+
+	/**
+	 * returns the responses property from a Components instance.
+	 *
+	 * @return Map&lt;String, ApiResponse&gt; responses
+	 **/
+
+	Map<String, ApiResponse> getResponses();
+
+	/**
+	 * sets this Components' responses property to the given map of ApiResponses.
+	 *
+	 * @param Map&lt;String, ApiResponse&gt;respones
+	 */
+	void setResponses(Map<String, ApiResponse> responses);
+
+	/**
+	 * sets this Components' responses property to the given map of ApiResponses and
+	 * return this instance of Components.
+	 *
+	 * @param Map&lt;String, ApiResponse&gt;responses
+	 */
+	Components responses(Map<String, ApiResponse> responses);
+
+	/**
+	 * Adds the given response to this Components' map of responses, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param ApiResponse responsesItem
+	 * @return Components instance
+	 */
+	Components addResponses(String key, ApiResponse responsesItem);
+
+	/**
+	 * returns the parameters property from a Components instance.
+	 *
+	 * @return Map&lt;String, Parameter&gt; parameters
+	 **/
+
+	Map<String, Parameter> getParameters();
+
+	/**
+	 * sets this Components' parameters property to the given map of Parameters.
+	 *
+	 * @param Map&lt;String, Parameter&gt;parameters
+	 */
+	void setParameters(Map<String, Parameter> parameters);
+
+	/**
+	 * sets this Components' parameters property to the given map of Parameters and
+	 * returns this instance of Components.
+	 *
+	 * @param Map&lt;String, Parameter&gt;parameters
+	 * @return Components
+	 */
+	Components parameters(Map<String, Parameter> parameters);
+
+	/**
+	 * Adds the given parameters to this Components' map of parameters, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param Parameter parametersItem
+	 * @return Components
+	 */
+	Components addParameters(String key, Parameter parametersItem);
+
+	/**
+	 * returns the examples property from a Components instance.
+	 *
+	 * @return Map&lt;String, Example&gt; examples
+	 **/
+
+	Map<String, Example> getExamples();
+
+	/**
+	 * sets this Components' examples property to the given map of Examples.
+	 *
+	 * @param Map&lt;String, Example&gt;examples
+	 */
+	void setExamples(Map<String, Example> examples);
+
+	/**
+	 * sets this Components' examples property to the given map of Examples and
+	 * returns this instance of Components.
+	 *
+	 * @param Map&lt;String, Example&gt;examples
+	 * @return Components
+	 */
+	Components examples(Map<String, Example> examples);
+
+	/**
+	 * Adds the given Example to this Components' map of Examples, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param Example examplesItem
+	 * @return Components
+	 */
+	Components addExamples(String key, Example examplesItem);
+
+	/**
+	 * returns the requestBodies property from a Components instance.
+	 *
+	 * @return Map&lt;String, RequestBody&gt; requestBodies
+	 **/
+
+	Map<String, RequestBody> getRequestBodies();
+
+	/**
+	 * sets this Components' requestBodies property to the given map of RequestBodies.
+	 *
+	 * @param Map&lt;String, RequestBody&gt;requestBodies
+	 */
+	void setRequestBodies(Map<String, RequestBody> requestBodies);
+
+	/**
+	 * sets this Components' requestBodies property to the given map of RequestBodies and
+	 * returns this instance of Components.
+	 *
+	 * @param Map&lt;String, RequestBody&gt;requestBodies
+	 * @return Components
+	 */
+	Components requestBodies(Map<String, RequestBody> requestBodies);
+
+	/**
+	 * Adds the given RequestBody to this Components' map of RequestBodies, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param RequestBody requestBodiesItem
+	 * @return Components
+	 */
+	Components addRequestBodies(String key, RequestBody requestBodiesItem);
+
+	/**
+	 * returns the headers property from a Components instance.
+	 *
+	 * @return Map&lt;String, Header&gt; headers
+	 **/
+
+	Map<String, Header> getHeaders();
+
+	/**
+	 * sets this Components' headers property to the given map of Headers.
+	 *
+	 * @param Map&lt;String, Header&gt;headers
+	 */
+	void setHeaders(Map<String, Header> headers);
+
+	/**
+	 * sets this Components' headers property to the given map of Headers and
+	 * returns this instance of Components.
+	 *
+	 * @param Map&lt;String, Header&gt;headers
+	 * @return Components
+	 */
+	Components headers(Map<String, Header> headers);
+
+	/**
+	 * Adds the given Header to this Components' map of Headers, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param Header headersItem
+	 * @return Components
+	 */
+	Components addHeaders(String key, Header headersItem);
+
+	/**
+	 * returns the securitySchemes property from a Components instance.
+	 *
+	 * @return Map&lt;String, SecurityScheme&gt; securitySchemes
+	 **/
+
+	Map<String, SecurityScheme> getSecuritySchemes();
+
+	/**
+	 * sets this Components' securitySchemes property to the given map of SecuritySchemes.
+	 *
+	 * @param Map&lt;String, SecurityScheme&gt;securitySchemes
+	 */
+	void setSecuritySchemes(Map<String, SecurityScheme> securitySchemes);
+
+	/**
+	 * sets this Components' securitySchemes property to the given map of SecuritySchemes and
+	 * returns this instance of Components.
+	 *
+	 * @param Map&lt;String, SecurityScheme&gt;securitySchemes
+	 * @return Components
+	 */
+	Components securitySchemes(Map<String, SecurityScheme> securitySchemes);
+
+	/**
+	 * Adds the given SecurityScheme to this Components' map of SecuritySchemes, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param SecurityScheme securitySchemesItem
+	 * @return Components
+	 */
+	Components addSecuritySchemes(String key, SecurityScheme securitySchemesItem);
+
+	/**
+	 * returns the links property from a Components instance.
+	 *
+	 * @return Map&lt;String, Link&gt; links
+	 **/
+
+	Map<String, Link> getLinks();
+
+	/**
+	 * sets this Components' links property to the given map of Links.
+	 *
+	 * @param Map&lt;String, Link&gt;links
+	 */
+	void setLinks(Map<String, Link> links);
+
+	/**
+	 * sets this Components' links property to the given map of Links and
+	 * returns this instance of Components.
+	 *
+	 * @param Map&lt;String, Link&gt;links
+	 * @return Components
+	 */
+	Components links(Map<String, Link> links);
+
+	/**
+	 * Adds the given Link to this Components' map of Links, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param Link linksItem
+	 * @return Components
+	 */
+	Components addLinks(String key, Link linksItem);
+
+	/**
+	 * returns the callbacks property from a Components instance.
+	 *
+	 * @return Map&lt;String, Callback&gt; callbacks
+	 **/
+
+	Map<String, Callback> getCallbacks();
+
+	/**
+	 * sets this Components' callbacks property to the given map of Callbacks.
+	 *
+	 * @param Map&lt;String, Callback&gt;callbacks
+	 */
+	void setCallbacks(Map<String, Callback> callbacks);
+
+	/**
+	 * sets this Components' callbacks property to the given map of Callbacks and
+	 * returns this instance of Components.
+	 *
+	 * @param Map&lt;String, Callback&gt;callbacks
+	 * @return Components
+	 */
+	Components callbacks(Map<String, Callback> callbacks);
+
+	/**
+	 * Adds the given Callback to this Components' map of Callbacks, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param Callback callbacksItem
+	 * @return Components
+	 */
+	Components addCallbacks(String key, Callback callbacksItem);
+
+	/**
+	 * returns the extensions property from a Components instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 **/
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds the given Object to this Components' map of extensions, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param Object value
+	 * @return Components
+	 */
+	void addExtension(String name, Object value);
+
+	/**
+	 * sets this Components' extensions property to the given map of extensions.
+	 *
+	 * @param Map&lt;String, Object&gt;extensions
+	 */
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/Constructible.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/Constructible.java
new file mode 100644
index 000000000..55015dbfa
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Constructible.java
@@ -0,0 +1,21 @@
+/**
+ * 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.models;
+
+public interface Constructible {
+
+}
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
new file mode 100644
index 000000000..8bc22bdf0
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
@@ -0,0 +1,100 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models;
+
+import java.util.Map;
+
+/**
+ * ExternalDocumentation
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#externalDocumentationObject"
+ */
+public interface ExternalDocumentation extends Constructible {
+
+	/**
+	   * returns the description property from a ExternalDocumentation instance.
+	   *
+	   * @return String description
+	   **/
+
+	String getDescription();
+
+	/**
+	   * sets this ExternalDocumentation's description property to the given description.
+	   *
+	   * @param String description
+	   */
+	void setDescription(String description);
+
+	/**
+	   * sets this ExternalDocumentation's description property to the given description and
+	   * returns this instance of ExternalDocumentation.
+	   *
+	   * @param String description
+	   * @return ExternalDocumentation
+	   */
+	ExternalDocumentation description(String description);
+
+	/**
+	   * returns the url property from a ExternalDocumentation instance.
+	   *
+	   * @return String url
+	   **/
+
+	String getUrl();
+
+	/**
+	   * sets this ExternalDocumentation's url property to the given url.
+	   *
+	   * @param String url
+	   */
+	void setUrl(String url);
+
+	/**
+	   * sets this ExternalDocumentation's url property to the given url and
+	   * returns this instance of ExternalDocumentation.
+	   *
+	   * @param String url
+	   * @return ExternalDocumentation
+	   */
+	ExternalDocumentation url(String url);
+
+	/**
+	   * returns the extensions property from a ExternalDocumentation instance.
+	   *
+	   * @return Map&lt;String, Object&gt;extensions
+	   **/
+	Map<String, Object> getExtensions();
+
+	/**
+	   * Adds the given extension to this ExternalDocumentation's map of extensions, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param Object value
+	   * @return Components
+	   */
+	void addExtension(String name, Object value);
+
+	/**
+	   * sets this ExternalDocumentation's extensions property to the given extensions.
+	   *
+	   * @param Map&lt;String, Object&gt;extensions
+	   */
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
new file mode 100644
index 000000000..e750b8102
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
@@ -0,0 +1,305 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models;
+
+import java.util.List;
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.info.Info;
+import org.eclipse.microprofile.openapi.models.media.Schema;
+import org.eclipse.microprofile.openapi.models.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.models.security.SecurityScheme;
+import org.eclipse.microprofile.openapi.models.servers.Server;
+import org.eclipse.microprofile.openapi.models.tags.Tag;
+
+/**
+ * OpenAPI
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md"
+ */
+public interface OpenAPI extends Constructible {
+
+	/**
+	   * returns the openapi property from a OpenAPI instance.
+	   *
+	   * @return String openapi
+	   **/
+
+	String getOpenapi();
+
+	/**
+	   * sets this OpenAPI's openapi property to the given openapi.
+	   *
+	   * @param String openapi
+	   */
+	void setOpenapi(String openapi);
+
+	/**
+	   * sets this OpenAPI's openapi property to the given openapi and
+	   * returns this instance of OpenAPI
+	   *
+	   * @param String openapi
+	   * @return OpenAPI
+	   */
+	OpenAPI openapi(String openapi);
+
+	/**
+	   * returns the info property from a OpenAPI instance.
+	   *
+	   * @return Info info
+	   **/
+
+	Info getInfo();
+
+	/**
+	   * sets this OpenAPI's info property to the given info.
+	   *
+	   * @param Info info
+	   */
+	void setInfo(Info info);
+
+	/**
+	   * sets this OpenAPI's info property to the given info and
+	   * returns this instance of OpenAPI
+	   *
+	   * @param Info info
+	   * @return OpenAPI
+	   */
+	OpenAPI info(Info info);
+
+	/**
+	   * returns the externalDocs property from a OpenAPI instance.
+	   *
+	   * @return ExternalDocumentation externalDocs
+	   **/
+	ExternalDocumentation getExternalDocs();
+
+	/**
+	   * sets this OpenAPI's externalDocs property to the given externalDocs.
+	   *
+	   * @param ExternalDocumentation externalDocs
+	   */
+	void setExternalDocs(ExternalDocumentation externalDocs);
+
+	/**
+	   * sets this OpenAPI's externalDocs property to the given externalDocs and
+	   * returns this instance of OpenAPI
+	   *
+	   * @param ExternalDocumentation externalDocs
+	   * @return OpenAPI
+	   */
+	OpenAPI externalDocs(ExternalDocumentation externalDocs);
+
+	/**
+	   * returns the Servers defined in the API
+	   *
+	   * @return List&lt;Server&gt; servers
+	   **/
+
+	List<Server> getServers();
+
+	/**
+	   * sets this OpenAPI's servers property to the given servers.
+	   *
+	   * @param List&lt;Server&gt;servers
+	   */
+	void setServers(List<Server> servers);
+
+	/**
+	   * sets this OpenAPI's servers property to the given servers and
+	   * returns this instance of OpenAPI
+	   *
+	   * @param List&lt;Server&gt;servers
+	   * @return OpenAPI
+	   */
+	OpenAPI servers(List<Server> servers);
+
+	/**
+	   * Adds the given serversItem to this OpenAPI's list of servers, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param Server serversItem
+	   * @return OpenAPI
+	   */
+	OpenAPI addServersItem(Server serversItem);
+
+	/**
+	   * returns the security property from a OpenAPI instance.
+	   *
+	   * @return List&lt;SecurityRequirement&gt; security
+	   **/
+
+	List<SecurityRequirement> getSecurity();
+
+	/**
+	   * sets this OpenAPI's security property to the given security.
+	   *
+	   * @param List&lt;SecurityRequirement&gt;security
+	   */
+	void setSecurity(List<SecurityRequirement> security);
+
+	/**
+	   * sets this OpenAPI's security property to the given security and
+	   * returns this instance of OpenAPI
+	   *
+	   * @param List&lt;SecurityRequirement&gt;servers
+	   * @return OpenAPI
+	   */
+	OpenAPI security(List<SecurityRequirement> security);
+
+	/**
+	   * Adds the given securityItem to this OpenAPI's list of securitItems, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param SecurityRequirement securityItem
+	   * @return OpenAPI
+	   */
+	OpenAPI addSecurityItem(SecurityRequirement securityItem);
+
+	/**
+	   * returns the tags property from a OpenAPI instance.
+	   *
+	   * @return List&lt;Tag&gt; tags
+	   **/
+
+	List<Tag> getTags();
+
+	/**
+	   * sets this OpenAPI's tags property to the given Tags.
+	   *
+	   * @param List&lt;Tag&gt;tags
+	   */
+	void setTags(List<Tag> tags);
+
+	/**
+	   * sets this OpenAPI's tags property to the given tags and
+	   * returns this instance of OpenAPI
+	   *
+	   * @param List&lt;Tag&gt;tags
+	   * @return OpenAPI
+	   */
+	OpenAPI tags(List<Tag> tags);
+
+	/**
+	   * Adds the given tagsItem to this OpenAPI's list of tags, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param Tag tagsItem
+	   * @return OpenAPI
+	   */
+	OpenAPI addTagsItem(Tag tagsItem);
+
+	/**
+	   * returns the paths property from a OpenAPI instance.
+	   *
+	   * @return Paths paths
+	   **/
+
+	Paths getPaths();
+
+	/**
+	   * sets this OpenAPI's paths property to the given paths.
+	   *
+	   * @param List&lt;Paths&gt;paths
+	   */
+	void setPaths(Paths paths);
+
+	/**
+	   * sets this OpenAPI's paths property to the given paths and
+	   * returns this instance of OpenAPI
+	   *
+	   * @param List&lt;Paths&gt;paths
+	   * @return OpenAPI
+	   */
+	OpenAPI paths(Paths paths);
+
+	/**
+	   * returns the components property from a OpenAPI instance.
+	   *
+	   * @return Components components
+	   **/
+
+	Components getComponents();
+
+	/**
+	   * sets this OpenAPI's components property to the given components.
+	   *
+	   * @param List&lt;Components&gt;components
+	   */
+	void setComponents(Components components);
+
+	/**
+	   * sets this OpenAPI's components property to the given components and
+	   * returns this instance of OpenAPI
+	   *
+	   * @param List&lt;Components&gt;components
+	   * @return OpenAPI
+	   */
+	OpenAPI components(Components components);
+
+	/**
+	   * Adds the given path item to this OpenAPI's list of paths
+	   * 
+	   * @param String name
+	   * @param PathItem path
+	   * @return OpenAPI
+	   */
+	OpenAPI path(String name, PathItem path);
+
+	/**
+	   * Adds the given schema to this OpenAPI's components property.
+	   * 
+	   * @param String name
+	   * @param Schema schema
+	   * @return OpenAPI
+	   */
+	OpenAPI schema(String name, Schema schema);
+
+	/**
+	   * Adds the given securityScheme to this OpenAPI's securitySchemes
+	   * 
+	   * @param String name
+	   * @param SecurityScheme securityScheme
+	   * @return OpenAPI
+	   */
+	OpenAPI schemaRequirement(String name, SecurityScheme securityScheme);
+
+	/**
+	   * returns the extensions property from a OpenAPI instance.
+	   *
+	   * @return Map&lt;String, Object&gt; extensions
+	   **/
+	Map<String, Object> getExtensions();
+
+	/**
+	   * Adds the given Object to this OpenAPI's map of extensions, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param Object value
+	   * @return OpenAPI
+	   */
+	void addExtension(String name, Object value);
+
+	/**
+	   * sets this OpenAPI's extensions property to the given map of extensions.
+	   *
+	   * @param Map&lt;String, Object&gt;extensions
+	   */
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
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
new file mode 100644
index 000000000..02ff7fa19
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Operation.java
@@ -0,0 +1,383 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models;
+
+import java.util.List;
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.callbacks.Callback;
+import org.eclipse.microprofile.openapi.models.parameters.Parameter;
+import org.eclipse.microprofile.openapi.models.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.models.responses.ApiResponses;
+import org.eclipse.microprofile.openapi.models.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.models.servers.Server;
+
+/**
+ * Operation
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#operationObject"
+ */
+public interface Operation extends Constructible {
+
+	/**
+	   * returns the tags property from a Operation instance.
+	   *
+	   * @return List&lt;String&gt; tags
+	   **/
+
+	List<String> getTags();
+
+	/**
+	   * sets this Operation's tags property to the given Tags.
+	   *
+	   * @param List&lt;String&gt;tags
+	   */
+	void setTags(List<String> tags);
+
+	/**
+	   * sets this Operation's tags property to the given tags and
+	   * returns this instance of Operation
+	   *
+	   * @param List&lt;String&gt;tags
+	   * @return Operation
+	   */
+	Operation tags(List<String> tags);
+
+	/**
+	   * Adds the given tagsItem to this Operation's list of tags, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param String tagsItem
+	   * @return Operation
+	   */
+	Operation addTagsItem(String tagsItem);
+
+	/**
+	   * returns the summary property from a Operation instance.
+	   *
+	   * @return String summary
+	   **/
+
+	String getSummary();
+
+	/**
+	   * sets this Operation's summary property to the given summary.
+	   *
+	   * @param String summary
+	   */
+	void setSummary(String summary);
+
+	/**
+	   * sets this Operation's summary property to the given summary and
+	   * returns this instance of Operation
+	   *
+	   * @param String summary
+	   * @return Operation
+	   */
+	Operation summary(String summary);
+
+	/**
+	   * returns the description property from a Operation instance.
+	   *
+	   * @return String description
+	   **/
+	String getDescription();
+
+	/**
+	   * sets this Operation's description property to the given description.
+	   *
+	   * @param String description
+	   */
+	void setDescription(String description);
+
+	/**
+	   * sets this Operation's description property to the given description and
+	   * returns this instance of Operation
+	   *
+	   * @param String description
+	   * @return Operation
+	   */
+	Operation description(String description);
+
+	/**
+	   * returns the externalDocs property from a Operation instance.
+	   *
+	   * @return ExternalDocumentation externalDocs
+	   **/
+
+	ExternalDocumentation getExternalDocs();
+
+	/**
+	   * sets this Operation's externalDocs property to the given externalDocs.
+	   *
+	   * @param ExternalDocumentation externalDocs
+	   */
+	void setExternalDocs(ExternalDocumentation externalDocs);
+
+	/**
+	   * sets this Operation's externalDocs property to the given externalDocs and
+	   * returns this instance of Operation
+	   *
+	   * @param ExternalDocumentation externalDocs
+	   * @return Operation
+	   */
+	Operation externalDocs(ExternalDocumentation externalDocs);
+
+	/**
+	   * returns the operationId property from a Operation instance.
+	   *
+	   * @return String operationId
+	   **/
+
+	String getOperationId();
+
+	/**
+	   * sets this Operation's operationId property to the given operationId.
+	   *
+	   * @param String operationId
+	   */
+	void setOperationId(String operationId);
+
+	/**
+	   * sets this Operation's operationId property to the given operationId and
+	   * returns this instance of Operation
+	   *
+	   * @param String operationId
+	   * @return Operation
+	   */
+	Operation operationId(String operationId);
+
+	/**
+	   * returns the parameters property from a Operation instance.
+	   *
+	   * @return List&lt;Parameter&gt; parameters
+	   **/
+
+	List<Parameter> getParameters();
+
+	/**
+	   * sets this Operation's parameters property to the given parameters.
+	   *
+	   * @param List&lt;Parameter&gt;parameters
+	   */
+	void setParameters(List<Parameter> parameters);
+
+	/**
+	   * sets this Operation's parameters property to the given parameters and
+	   * returns this instance of Operation
+	   *
+	   * @param List&lt;Parameter&gt;parameters
+	   * @return Operation
+	   */
+	Operation parameters(List<Parameter> parameters);
+
+	/**
+	   * Adds the given parametersItem to this Operation's list of parameters, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param Parameter parametersItem
+	   * @return Operation
+	   */
+	Operation addParametersItem(Parameter parametersItem);
+
+	/**
+	   * returns the requestBody property from a Operation instance.
+	   *
+	   * @return RequestBody requestBody
+	   **/
+
+	RequestBody getRequestBody();
+
+	/**
+	   * sets this Operation's requestBody property to the given requestBody.
+	   *
+	   * @param RequestBody requestBody
+	   */
+	void setRequestBody(RequestBody requestBody);
+
+	/**
+	   * sets this Operation's requestBody property to the given requestBody and
+	   * returns this instance of Operation
+	   *
+	   * @param RequestBody requestBody
+	   * @return Operation
+	   */
+	Operation requestBody(RequestBody requestBody);
+
+	/**
+	   * returns the responses property from a Operation instance.
+	   *
+	   * @return ApiResponses responses
+	   **/
+
+	ApiResponses getResponses();
+
+	/**
+	   * sets this Operation's responses property to the given responses.
+	   *
+	   * @param ApiResponses responses
+	   */
+	void setResponses(ApiResponses responses);
+
+	/**
+	   * sets this Operation's responses property to the given responses and
+	   * returns this instance of Operation
+	   *
+	   * @param ApiResponses responses
+	   * @return Operation
+	   */
+	Operation responses(ApiResponses responses);
+
+	/**
+	   * returns the callbacks property from a Operation instance.
+	   *
+	   * @return Callbacks callbacks
+	   **/
+
+	Map<String, Callback> getCallbacks();
+
+	/**
+	   * sets this Operation's callbacks property to the given callbacks.
+	   *
+	   * @param Map&lt;String, Callback&gt; callbacks
+	   */
+	void setCallbacks(Map<String, Callback> callbacks);
+
+	/**
+	   * sets this Operation's callbacks property to the given callbacks and
+	   * returns this instance of Operation
+	   *
+	   * @param Map&lt;String, Callback&gt; callbacks
+	   * @return Operation
+	   */
+	Operation callbacks(Map<String, Callback> callbacks);
+
+	/**
+	   * returns the deprecated property from a Operation instance.
+	   *
+	   * @return Boolean deprecated
+	   **/
+
+	Boolean getDeprecated();
+
+	/**
+	   * sets this Operation's deprecated property to the given deprecated.
+	   *
+	   * @param Boolean deprecated
+	   */
+	void setDeprecated(Boolean deprecated);
+
+	/**
+	   * sets this Operation's deprecated property to the given deprecated and
+	   * returns this instance of Operation
+	   *
+	   * @param Boolean deprecated
+	   * @return Operation
+	   */
+	Operation deprecated(Boolean deprecated);
+
+	/**
+	   * returns the security property from a Operation instance.
+	   *
+	   * @return List&lt;SecurityRequirement&gt; security
+	   **/
+
+	List<SecurityRequirement> getSecurity();
+
+	/**
+	   * sets this Operation's security property to the given security.
+	   *
+	   * @param List&lt;SecurityRequirement&gt; security
+	   */
+	void setSecurity(List<SecurityRequirement> security);
+
+	/**
+	   * sets this Operation's security property to the given security and
+	   * returns this instance of Operation
+	   *
+	   * @param List&lt;SecurityRequirement&gt;security
+	   * @return Operation
+	   */
+	Operation security(List<SecurityRequirement> security);
+
+	/**
+	   * Adds the given securityItem to this Operation's list of securityItems, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param SecurityRequirement securityItem
+	   * @return Operation
+	   */
+	Operation addSecurityItem(SecurityRequirement securityItem);
+
+	/**
+	   * returns the servers property from a Operation instance.
+	   *
+	   * @return List&lt;Server&gt; servers
+	   **/
+
+	List<Server> getServers();
+
+	/**
+	   * sets this Operation's servers property to the given servers.
+	   *
+	   * @param List&lt;Server&gt; servers
+	   */
+	void setServers(List<Server> servers);
+
+	/**
+	   * sets this Operation's servers property to the given servers and
+	   * returns this instance of Operation
+	   *
+	   * @param List&lt;Server&gt;servers
+	   * @return Operation
+	   */
+	Operation servers(List<Server> servers);
+
+	/**
+	   * Adds the given serversItem to this Operation's list of serversItem, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param Server serversItem
+	   * @return Operation
+	   */
+	Operation addServersItem(Server serversItem);
+
+	/**
+	   * returns the extensions property from a Operation instance.
+	   *
+	   * @return Map&lt;String, Object&gt; extensions
+	   **/
+	Map<String, Object> getExtensions();
+
+	/**
+	   * Adds the given Object to this Operation's map of extensions, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param Object value
+	   * @return Operation
+	   */
+	void addExtension(String name, Object value);
+
+	/**
+	   * sets this Operation's extensions property to the given map of extensions.
+	   *
+	   * @param Map&lt;String, Object&gt;extensions
+	   */
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
new file mode 100644
index 000000000..f93fa6b26
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
@@ -0,0 +1,411 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models;
+
+import java.util.List;
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.parameters.Parameter;
+import org.eclipse.microprofile.openapi.models.servers.Server;
+
+/**
+ * PathItem
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#pathItemObject"
+ */
+public interface PathItem extends Constructible {
+
+	/**
+	 * All of the possible types of methods for this path
+	 */
+	enum HttpMethod {
+	    POST,
+	    GET,
+	    PUT,
+	    PATCH,
+	    DELETE,
+	    HEAD,
+	    OPTIONS,
+	    TRACE
+	}
+
+	/**
+	 * returns the summary property from a PathItem instance.
+	 *
+	 * @return String summary
+	 **/
+
+	String getSummary();
+
+	/**
+	 * sets this PathItem's summary property to the given summary.
+	 *
+	 * @param String summary
+	 */
+	void setSummary(String summary);
+
+	/**
+	* sets this PathItem's summary property to the given summary and
+	* returns this instance of PathItem
+	*
+	* @param String summary
+	* @return PathItem
+	*/
+	PathItem summary(String summary);
+
+	/**
+	 * returns the description property from a PathItem instance.
+	 *
+	 * @return String description
+	 **/
+
+	String getDescription();
+
+	/**
+	 * sets this PathItem's description property to the given description.
+	 *
+	 * @param String description
+	 */
+	void setDescription(String description);
+
+	/**
+	* sets this PathItem's description property to the given description and
+	* returns this instance of PathItem
+	*
+	* @param String description
+	* @return PathItem
+	*/
+	PathItem description(String description);
+
+	/**
+	 * returns the get property from a PathItem instance.
+	 *
+	 * @return Operation get
+	 **/
+	Operation getGet();
+
+	/**
+	 * sets this PathItem's get property to the given get.
+	 *
+	 * @param Operation get
+	 */
+	void setGet(Operation get);
+
+	/**
+	* sets this PathItem's get property to the given get and
+	* returns this instance of PathItem
+	*
+	* @param Operation get
+	* @return PathItem
+	*/
+	PathItem get(Operation get);
+
+	/**
+	 * returns the put property from a PathItem instance.
+	 *
+	 * @return Operation put
+	 **/
+
+	Operation getPut();
+
+	/**
+	 * sets this PathItem's put property to the given put.
+	 *
+	 * @param Operation put
+	 */
+	void setPut(Operation put);
+
+	/**
+	* sets this PathItem's put property to the given put and
+	* returns this instance of PathItem
+	*
+	* @param Operation put
+	* @return PathItem
+	*/
+	PathItem put(Operation put);
+
+	/**
+	 * returns the post property from a PathItem instance.
+	 *
+	 * @return Operation post
+	 **/
+
+	Operation getPost();
+
+	/**
+	 * sets this PathItem's post property to the given post.
+	 *
+	 * @param Operation post
+	 */
+	void setPost(Operation post);
+
+	/**
+	* sets this PathItem's post property to the given post and
+	* returns this instance of PathItem
+	*
+	* @param Operation post
+	* @return PathItem
+	*/
+	PathItem post(Operation post);
+
+	/**
+	 * returns the delete property from a PathItem instance.
+	 *
+	 * @return Operation delete
+	 **/
+
+	Operation getDelete();
+
+	/**
+	 * sets this PathItem's delete property to the given delete.
+	 *
+	 * @param Operation delete
+	 */
+	void setDelete(Operation delete);
+
+	/**
+	* sets this PathItem's delete property to the given delete and
+	* returns this instance of PathItem
+	*
+	* @param Operation delete
+	* @return PathItem
+	*/
+	PathItem delete(Operation delete);
+
+	/**
+	 * returns the options property from a PathItem instance.
+	 *
+	 * @return Operation options
+	 **/
+
+	Operation getOptions();
+
+	/**
+	 * sets this PathItem's options property to the given options.
+	 *
+	 * @param Operation options
+	 */
+	void setOptions(Operation options);
+
+	/**
+	* sets this PathItem's options property to the given options and
+	* returns this instance of PathItem
+	*
+	* @param Operation options
+	* @return PathItem
+	*/
+	PathItem options(Operation options);
+
+	/**
+	 * returns the head property from a PathItem instance.
+	 *
+	 * @return Operation head
+	 **/
+
+	Operation getHead();
+
+	/**
+	 * sets this PathItem's head property to the given head.
+	 *
+	 * @param Operation head
+	 */
+	void setHead(Operation head);
+
+	/**
+	* sets this PathItem's head property to the given head and
+	* returns this instance of PathItem
+	*
+	* @param Operation head
+	* @return PathItem
+	*/
+	PathItem head(Operation head);
+
+	/**
+	 * returns the patch property from a PathItem instance.
+	 *
+	 * @return Operation patch
+	 **/
+
+	Operation getPatch();
+
+	/**
+	 * sets this PathItem's patch property to the given patch.
+	 *
+	 * @param Operation patch
+	 */
+	void setPatch(Operation patch);
+
+	/**
+	* sets this PathItem's patch property to the given patch and
+	* returns this instance of PathItem
+	*
+	* @param Operation patch
+	* @return PathItem
+	*/
+	PathItem patch(Operation patch);
+
+	/**
+	 * returns the trace property from a PathItem instance.
+	 *
+	 * @return Operation trace
+	 **/
+
+	Operation getTrace();
+
+	/**
+	 * sets this PathItem's trace property to the given trace.
+	 *
+	 * @param Operation trace
+	 */
+	void setTrace(Operation trace);
+
+	/**
+	* sets this PathItem's trace property to the given trace and
+	* returns this instance of PathItem
+	*
+	* @param Operation trace
+	* @return PathItem
+	*/
+	PathItem trace(Operation trace);
+
+	/**
+	 * Returns a list of all the operation for this path.
+	 * 
+	 * @return List&lt;Operation&gt; allOperations
+	 */
+	List<Operation> readOperations();
+
+	/**
+	 * Returns a map with all the operations for this path, where the HttpMethods are keys.
+	 * 
+	 * @return Map&lt;HttpMethod, Operation&gt; result
+	 */
+	Map<PathItem.HttpMethod, Operation> readOperationsMap();
+
+	/**
+	 * returns the servers property from a PathItem instance.
+	 *
+	 * @return List&lt;Server&gt; servers
+	 **/
+
+	List<Server> getServers();
+
+	/**
+	 * sets this PathItem's servers property to the given servers.
+	 *
+	 * @param List&lt;Server&gt; servers
+	 */
+	void setServers(List<Server> servers);
+
+	/**
+	* sets this PathItem's patch servers to the given servers and
+	* returns this instance of PathItem
+	*
+	* @param List&lt;Server&gt; servers
+	* @return PathItem
+	*/
+	PathItem servers(List<Server> servers);
+
+	/**
+	 * Adds the given serversItem to this PathItem's list of serversItem, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param Server serversItem
+	 * @return PathItem
+	*/
+	PathItem addServersItem(Server serversItem);
+
+	/**
+	 * returns the parameters property from a PathItem instance.
+	 *
+	 * @return List&lt;Parameter&gt; parameters
+	 **/
+
+	List<Parameter> getParameters();
+
+	/**
+	 * sets this PathItem's parameters property to the given parameters.
+	 *
+	 * @param List&lt;Parameter&gt; servers
+	 */
+	void setParameters(List<Parameter> parameters);
+
+	/**
+	 * sets this PathItem's patch parameters to the given parameters and
+	 * returns this instance of PathItem
+	 *
+	 * @param List&lt;Parameter&gt; servers
+	 * @return PathItem
+	 */
+	PathItem parameters(List<Parameter> parameters);
+
+	/**
+	 * Adds the given parametersItem to this PathItem's list of parametersItem, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param Parameter parametersItem
+	 * @return PathItem
+	*/
+	PathItem addParametersItem(Parameter parametersItem);
+
+	/**
+	 * returns the extensions property from a PathItem instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 **/
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds the given extension to this PathItem's list of extension, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param Object value
+	*/
+	void addExtension(String name, Object value);
+
+	/**
+	 * sets this PathItem's patch extensions to the given extensions
+	 *
+	 * @param Map&lt;String, Object&gt; extensions
+	 **/
+	void setExtensions(Map<String, Object> extensions);
+
+	/**
+	 * returns the ref property from a PathItem instance.
+	 *
+	 * @return String ref
+	 **/
+	String get$ref();
+
+	/**
+	 * sets this PathItem's $ref property to the given $ref.
+	 *
+	 * @param String $ref
+	 */
+	void set$ref(String $ref);
+
+	/**
+	 * sets this PathItem's $ref parameters to the given $ref and
+	 * returns this instance of PathItem
+	 *
+	 * @param List&lt;String&gt; $ref
+	 * @return PathItem
+	 */
+	PathItem $ref(String $ref);
+
+}
\ No newline at end of file
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
new file mode 100644
index 000000000..c50554aa6
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Paths.java
@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models;
+
+import java.util.Map;
+
+/**
+ * Paths
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#pathsObject"
+ */
+public interface Paths extends Constructible, Map<String, PathItem> {
+
+	/**
+	   * Adds the given path item to this Paths and return this instance of Paths
+	   * 
+	   * @param String name
+	   * @param PathItem item
+	   * @return Paths
+	   */
+	Paths addPathItem(String name, PathItem item);
+
+	/**
+	   * returns the extensions property from a Paths instance.
+	   *
+	   * @return Map&lt;String, Object&gt; extensions
+	   **/
+	Map<String, Object> getExtensions();
+
+	/**
+	   * Adds the given Object to this Paths' map of extensions, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param Object value
+	   * @return Paths
+	   */
+	void addExtension(String name, Object value);
+
+	/**
+	   * sets this Paths' extensions property to the given map of extensions.
+	   *
+	   * @param Map&lt;String, Object&gt;extensions
+	   */
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
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
new file mode 100644
index 000000000..282d34e07
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/callbacks/Callback.java
@@ -0,0 +1,63 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.callbacks;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.PathItem;
+
+/**
+ * Callback
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#callbackObject"
+ */
+public interface Callback extends Constructible, Map<String, PathItem> {
+
+	/**
+	   * Adds the given PathItem to this Callbacks's list of PathItems, with the given key as its key.
+	   *
+	   * @param String name
+	   * @param PathItem item
+	   */
+	Callback addPathItem(String name, PathItem item);
+
+	/**
+	   * returns the extensions property from a Callback instance.
+	   *
+	   * @return Map&lt;String, Object&gt; extensions
+	   **/
+	Map<String, Object> getExtensions();
+
+	/**
+	   * Adds the given Object to this Callback's map of extensions, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param Object value
+	   * @return Components
+	   */
+	void addExtension(String name, Object value);
+
+	/**
+	   * sets this Components' extensions property to the given map of extensions.
+	   *
+	   * @param Map&lt;String, Object&gt;extensions
+	   */
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/callbacks/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/callbacks/package-info.java
new file mode 100644
index 000000000..a2e13b949
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/callbacks/package-info.java
@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.openapi.models.callbacks;
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
new file mode 100644
index 000000000..59d9777c6
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
@@ -0,0 +1,168 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.examples;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * Example
+ */
+public interface Example extends Constructible {
+
+	/**
+	 * returns the summary property from a Example instance.
+	 *
+	 * @return String summary
+	 **/
+
+	String getSummary();
+
+	/**
+	 * sets this Example's summary property to the given summary.
+	 *
+	 * @param String summary
+	 */
+	void setSummary(String summary);
+
+	/**
+	 * sets this Example's summary property to the given summary and
+	 * returns this instance of Example
+	 *
+	 * @param String summary
+	 * @return Example
+	 */
+	Example summary(String summary);
+
+	/**
+	 * returns the description property from a Example instance.
+	 *
+	 * @return String description
+	 **/
+
+	String getDescription();
+
+	/**
+	 * sets this Example's description property to the given description.
+	 *
+	 * @param String description
+	 */
+	void setDescription(String description);
+
+	/**
+	 * sets this Example's description property to the given description and
+	 * returns this instance of Example
+	 *
+	 * @param String description
+	 * @return Example
+	 */
+	Example description(String description);
+
+	/**
+	 * returns the value property from a Example instance.
+	 *
+	 * @return Object value
+	 **/
+
+	Object getValue();
+
+	/**
+	 * sets this Example's value property to the given value.
+	 *
+	 * @param Object value
+	 */
+	void setValue(Object value);
+
+	/**
+	 * sets this Example's value property to the given value and
+	 * returns this instance of Example
+	 *
+	 * @param Object value
+	 * @return Example
+	 */
+	Example value(Object value);
+
+	/**
+	 * returns the externalValue property from a Example instance.
+	 *
+	 * @return String externalValue
+	 **/
+
+	String getExternalValue();
+
+	/**
+	 * sets this Example's externalValue property to the given externalValue.
+	 *
+	 * @param String externalValue
+	 */
+	void setExternalValue(String externalValue);
+
+	/**
+	 * sets this Example's externalValue property to the given externalValue and
+	 * returns this instance of Example
+	 *
+	 * @param String externalValue
+	 * @return Example
+	 */
+	Example externalValue(String externalValue);
+
+	/**
+	 * returns the $ref property from a Example instance.
+	 *
+	 * @return String $ref
+	 */
+	String get$ref();
+
+	/**
+	 * sets this Example's $ref property to the given $ref.
+	 *
+	 * @param String $ref
+	 */
+	void set$ref(String $ref);
+
+	/**
+	 * sets this Example's $ref property to the given $ref and
+	 * returns this instance of Example
+	 *
+	 * @param String $ref
+	 * @return Example
+	 */
+	Example $ref(String $ref);
+
+	/**
+	 * returns the extensions property from a Example instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 **/
+	java.util.Map<String, Object> getExtensions();
+
+	/**
+	 * Adds the given Object to this Example's map of extensions, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param Object value
+	 */
+	void addExtension(String name, Object value);
+
+	/**
+	 * sets the extensions property for a Example instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 **/
+	void setExtensions(java.util.Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/package-info.java
new file mode 100644
index 000000000..b5b65ab6a
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/package-info.java
@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.openapi.models.examples;
\ No newline at end of file
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
new file mode 100644
index 000000000..9153f3d7c
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/headers/Header.java
@@ -0,0 +1,345 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.headers;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.examples.Example;
+import org.eclipse.microprofile.openapi.models.media.Content;
+import org.eclipse.microprofile.openapi.models.media.Schema;
+
+public interface Header extends Constructible {
+	
+    /**
+     * Gets or Sets style
+     */
+    public enum StyleEnum {
+        SIMPLE("simple");
+
+        private final String value;
+
+        StyleEnum(String value) {
+            this.value = value;
+        }
+
+        @Override
+        public String toString() {
+            return String.valueOf(value);
+        }
+    }
+
+	/**
+	 * returns the description property from a Header instance.
+	 *
+	 * @return String description
+	 **/
+
+	String getDescription();
+
+	/**
+	 * sets this Header's description property to the given description.
+	 *
+	 * @param String description
+	 */
+	void setDescription(String description);
+
+	/**
+	 * sets this Header's description property to the given description and
+	 * returns this instance of Header
+	 *
+	 * @param String description
+	 * @return Header
+	 */
+	Header description(String description);
+
+	/**
+	 * returns the required property from a Header instance.
+	 *
+	 * @return Boolean required
+	 **/
+
+	Boolean getRequired();
+
+	/**
+	 * sets this Header's required property to the given required.
+	 *
+	 * @param Boolean required
+	 */
+	void setRequired(Boolean required);
+
+	/**
+	 * sets this Header's required property to the given required and
+	 * returns this instance of Header
+	 *
+	 * @param Boolean required
+	 * @return Header
+	 */
+	Header required(Boolean required);
+
+	/**
+	 * returns the deprecated property from a Header instance.
+	 *
+	 * @return Boolean deprecated
+	 **/
+
+	Boolean getDeprecated();
+
+	/**
+	 * sets this Header's deprecated property to the given deprecated.
+	 *
+	 * @param Boolean deprecated
+	 */
+	void setDeprecated(Boolean deprecated);
+
+	/**
+	 * sets this Header's deprecated property to the given deprecated and
+	 * returns this instance of Header
+	 *
+	 * @param Boolean deprecated
+	 * @return Header
+	 */
+	Header deprecated(Boolean deprecated);
+
+	/**
+	 * returns the allowEmptyValue property from a Header instance.
+	 *
+	 * @return Boolean allowEmptyValue
+	 **/
+
+	Boolean getAllowEmptyValue();
+
+	/**
+	 * sets this Header's allowEmptyValue property to the given allowEmptyValue.
+	 *
+	 * @param Boolean allowEmptyValue
+	 */
+	void setAllowEmptyValue(Boolean allowEmptyValue);
+
+	/**
+	 * sets this Header's allowEmptyValue property to the given allowEmptyValue and
+	 * returns this instance of Header
+	 *
+	 * @param Boolean allowEmptyValue
+	 * @return Header
+	 */
+	Header allowEmptyValue(Boolean allowEmptyValue);
+
+	/**
+	 * returns the style property from a Header instance.
+	 *
+	 * @return StyleEnum style
+	 **/
+
+	StyleEnum getStyle();
+
+	/**
+	 * sets this Header's style property to the given style.
+	 *
+	 * @param StyleEnum style
+	 */
+	void setStyle(StyleEnum style);
+
+	/**
+	 * sets this Header's style property to the given style and
+	 * returns this instance of Header
+	 *
+	 * @param StyleEnum style
+	 * @return Header
+	 */
+	Header style(StyleEnum style);
+
+	/**
+	 * returns the explode property from a Header instance.
+	 *
+	 * @return Boolean explode
+	 **/
+
+	Boolean getExplode();
+
+	/**
+	 * sets this Header's explode property to the given explode.
+	 *
+	 * @param Boolean allowEmptyValue
+	 */
+	void setExplode(Boolean explode);
+
+	/**
+	 * sets this Header's explode property to the given explode and
+	 * returns this instance of Header
+	 *
+	 * @param Boolean explode
+	 * @return Header
+	 */
+	Header explode(Boolean explode);
+
+	/**
+	 * returns the schema property from a Header instance.
+	 *
+	 * @return Schema schema
+	 **/
+
+	Schema getSchema();
+
+	/**
+	 * sets this Header's schema property to the given schema.
+	 *
+	 * @param Schema schema
+	 */
+	void setSchema(Schema schema);
+
+	/**
+	 * sets this Header's schema property to the given schema and
+	 * returns this instance of Header
+	 *
+	 * @param Schema schema
+	 * @return Header
+	 */
+	Header schema(Schema schema);
+
+	/**
+	 * returns the examples property from a Header instance.
+	 *
+	 * @return Map&lt;String, Example&gt; examples
+	 **/
+
+	Map<String, Example> getExamples();
+
+	/**
+	 * Sets the examples map of header instance to parameter.
+	 *
+	 * @param examples
+	 */
+
+	void setExamples(Map<String, Example> examples);
+
+	/**
+	 * Sets the examples map of header instance
+	 * to parameter and returns the instance.
+	 *
+	 * @param examples
+	 * @return Header instance with set examples map.
+	 */
+
+	Header examples(Map<String, Example> examples);
+
+	/**
+	 * Adds a key-value item to examples map
+	 * of header instance and returns the instance.
+	 *
+	 * @param key
+	 * @param examplesItem
+	 * @return Header instance with a key-value pair added to examples map
+	 */
+
+	Header addExample(String key, Example examplesItem);
+
+	/**
+	 * returns the example property from a Header instance.
+	 *
+	 * @return String example
+	 **/
+
+	String getExample();
+
+	/**
+	 * sets this Header's example property to the given example.
+	 *
+	 * @param String example
+	 */
+	void setExample(String example);
+
+	/**
+	 * sets this Header's example property to the given example and
+	 * returns this instance of Header
+	 *
+	 * @param String example
+	 * @return Header
+	 */
+	Header example(String example);
+
+	/**
+	 * returns the content property from a Header instance.
+	 *
+	 * @return Content content
+	 **/
+
+	Content getContent();
+
+	/**
+	 * sets this Header's content property to the given content.
+	 *
+	 * @param Content content
+	 */
+	void setContent(Content content);
+
+	/**
+	 * sets this Header's content property to the given content and
+	 * returns this instance of Header
+	 *
+	 * @param Content content
+	 * @return Header
+	 */
+	Header content(Content content);
+
+	/**
+	 * returns the extensions property from a Header instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+	java.util.Map<String, Object> getExtensions();
+
+	/**
+	 * Adds the given Object to this Header's map of extensions, with the given key as its key.
+	 *
+	 * @param String key
+	 * @param Object value
+	 */
+	void addExtension(String name, Object value);
+
+	/**
+	 * sets the extensions property for a Header instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+	void setExtensions(java.util.Map<String, Object> extensions);
+
+	/**
+	 * returns the $ref property from a Header instance.
+	 *
+	 * @return String $ref
+	 */
+	String get$ref();
+
+	/**
+	 * sets this Header's $ref property to the given $ref.
+	 *
+	 * @param String $ref
+	 */
+	void set$ref(String $ref);
+
+	/**
+	 * sets this Header's $ref property to the given $ref and
+	 * returns this instance of Header
+	 *
+	 * @param String $ref
+	 * @return Header
+	 */
+	Header $ref(String $ref);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/headers/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/headers/package-info.java
new file mode 100644
index 000000000..7b80dcf43
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/headers/package-info.java
@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.openapi.models.headers;
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java
new file mode 100644
index 000000000..881e4ac54
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java
@@ -0,0 +1,125 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.info;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * Contact
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#contactObject"
+ */
+public interface Contact extends Constructible {
+
+	/**
+	   * returns the name property from a Contact instance.
+	   *
+	   * @return String name
+	   **/
+
+	String getName();
+
+	/**
+	   * sets this Contact's name property to the given name.
+	   *
+	   * @param String name
+	   */
+	void setName(String name);
+
+	/**
+	   * sets this Contact's name property to the given name and
+	   * returns this instance of Contact
+	   *
+	   * @param String name
+	   * @return Contact
+	   */
+	Contact name(String name);
+
+	/**
+	   * returns the url property from a Contact instance.
+	   *
+	   * @return String url
+	   **/
+
+	String getUrl();
+
+	/**
+	   * sets this Contact's url property to the given url.
+	   *
+	   * @param String url
+	   */
+	void setUrl(String url);
+
+	/**
+	   * sets this Contact's url property to the given url and
+	   * returns this instance of Contact
+	   *
+	   * @param String url
+	   * @return Contact
+	   */
+	Contact url(String url);
+
+	/**
+	   * returns the email property from a Contact instance.
+	   *
+	   * @return String email
+	   **/
+
+	String getEmail();
+
+	/**
+	   * sets this Contact's email property to the given email.
+	   *
+	   * @param String email
+	   */
+	void setEmail(String email);
+
+	/**
+	   * sets this Contact's email property to the given email and
+	   * returns this instance of Contact
+	   *
+	   * @param String email
+	   * @return Contact
+	   */
+	Contact email(String email);
+
+	/**
+	   * returns the extensions property from a Contact instance.
+	   *
+	   * @return Map&lt;String, Object&gt; extensions
+	   */
+	Map<String, Object> getExtensions();
+
+	/**
+	   * Adds the given Object to this Contact's map of extensions, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param Object value
+	   */
+	void addExtension(String name, Object value);
+
+	/**
+	    * sets the extensions property for a Contact instance.
+	    *
+	    * @return Map&lt;String, Object&gt; extensions
+	    */
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
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
new file mode 100644
index 000000000..93ac273fa
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Info.java
@@ -0,0 +1,196 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.info;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+*
+* @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#infoObject"
+*/
+public interface Info extends Constructible {
+
+	/**
+	   * returns the title property from a Info instance.
+	   *
+	   * @return String title
+	   **/
+
+	String getTitle();
+
+	/**
+	   * sets this Info's title property to the given title.
+	   *
+	   * @param String title
+	   */
+	void setTitle(String title);
+
+	/**
+	   * sets this Info's title property to the given title and
+	   * returns this instance of Info
+	   *
+	   * @param String title
+	   * @return Info
+	   */
+	Info title(String title);
+
+	/**
+	   * returns the description property from a Info instance.
+	   *
+	   * @return String description
+	   **/
+
+	String getDescription();
+
+	/**
+	   * sets this Info's description property to the given description.
+	   *
+	   * @param String description
+	   */
+	void setDescription(String description);
+
+	/**
+	   * sets this Info's description property to the given description and
+	   * returns this instance of Info
+	   *
+	   * @param String description
+	   * @return Info
+	   */
+	Info description(String description);
+
+	/**
+	   * returns the termsOfService property from a Info instance.
+	   *
+	   * @return String termsOfService
+	   **/
+
+	String getTermsOfService();
+
+	/**
+	   * sets this Info's termsOfService property to the given termsOfService.
+	   *
+	   * @param String termsOfService
+	   */
+	void setTermsOfService(String termsOfService);
+
+	/**
+	   * sets this Info's termsOfService property to the given termsOfService and
+	   * returns this instance of Info
+	   *
+	   * @param String termsOfService
+	   * @return Info
+	   */
+	Info termsOfService(String termsOfService);
+
+	/**
+	   * returns the contact property from a Info instance.
+	   *
+	   * @return Contact contact
+	   **/
+
+	Contact getContact();
+
+	/**
+	   * sets this Info's contact property to the given contact.
+	   *
+	   * @param Contact contact
+	   */
+	void setContact(Contact contact);
+
+	/**
+	   * sets this Info's contact property to the given contact and
+	   * returns this instance of Info
+	   *
+	   * @param Contact contact
+	   * @return Info
+	   */
+	Info contact(Contact contact);
+
+	/**
+	   * returns the license property from a Info instance.
+	   *
+	   * @return License license
+	   **/
+
+	License getLicense();
+
+	/**
+	   * sets this Info's license property to the given license.
+	   *
+	   * @param License license
+	   */
+	void setLicense(License license);
+
+	/**
+	   * sets this Info's license property to the given license and
+	   * returns this instance of Info
+	   *
+	   * @param License license
+	   * @return Info
+	   */
+	Info license(License license);
+
+	/**
+	   * returns the version property from a Info instance.
+	   *
+	   * @return String version
+	   **/
+
+	String getVersion();
+
+	/**
+	   * sets this Info's version property to the given version.
+	   *
+	   * @param String version
+	   */
+	void setVersion(String version);
+
+	/**
+	   * sets this Info's version property to the given version and
+	   * returns this instance of Info
+	   *
+	   * @param String version
+	   * @return Info
+	   */
+	Info version(String version);
+
+	/**
+	   * returns the extensions property from a Info instance.
+	   *
+	   * @return Map&lt;String, Object&gt; extensions
+	   */
+	Map<String, Object> getExtensions();
+
+	/**
+	   * Adds the given Object to this Info's map of extensions, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param Object value
+	   */
+	void addExtension(String name, Object value);
+
+	/**
+	    * sets the extensions property for a Info instance.
+	    *
+	    * @return Map&lt;String, Object&gt; extensions
+	    */
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
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
new file mode 100644
index 000000000..951c04807
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/License.java
@@ -0,0 +1,96 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.info;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+public interface License extends Constructible {
+
+	/**
+	   * returns the name property from a License instance.
+	   *
+	   * @return String name
+	   **/
+
+	String getName();
+
+	/**
+	   * sets this License's name property to the given name.
+	   *
+	   * @param String name
+	   */
+	void setName(String name);
+
+	/**
+	   * sets this License's name property to the given name and
+	   * returns this instance of License
+	   *
+	   * @param String name
+	   * @return License
+	   */
+	License name(String name);
+
+	/**
+	   * returns the url property from a License instance.
+	   *
+	   * @return String url
+	   **/
+
+	String getUrl();
+
+	/**
+	   * sets this License's url property to the given url.
+	   *
+	   * @param String url
+	   */
+	void setUrl(String url);
+
+	/**
+	   * sets this License's url property to the given url and
+	   * returns this instance of License
+	   *
+	   * @param String url
+	   * @return License
+	   */
+	License url(String url);
+
+	/**
+	   * returns the extensions property from a License instance.
+	   *
+	   * @return Map&lt;String, Object&gt; extensions
+	   */
+	Map<String, Object> getExtensions();
+
+	/**
+	   * Adds the given Object to this License's map of extensions, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param Object value
+	   */
+	void addExtension(String name, Object value);
+
+	/**
+	   * sets the extensions property for a License instance.
+	   *
+	   * @return Map&lt;String, Object&gt; extensions
+	   */
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/package-info.java
new file mode 100644
index 000000000..036a43bd6
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/package-info.java
@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.openapi.models.info;
\ No newline at end of file
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
new file mode 100644
index 000000000..4b9027ee6
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/links/Link.java
@@ -0,0 +1,255 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.links;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.headers.Header;
+import org.eclipse.microprofile.openapi.models.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.models.servers.Server;
+
+/**
+ * Link
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#linkObject"
+ */
+public interface Link extends Constructible {
+
+	/**
+	 * returns the server property from a Link instance.
+	 *
+	 * @return Server server
+	 **/
+
+	Server getServer();
+
+	/**
+	 * sets this Link's server property to the given server.
+	 *
+	 * @param Server server
+	 */
+	void setServer(Server server);
+
+	/**
+	 * sets this Link's server property to the given server and
+	 * returns this instance of Link
+	 *
+	 * @param Server server
+	 * @return Link
+	 */
+	Link server(Server server);
+
+	/**
+	 * returns the operationRef property from a Link instance.
+	 *
+	 * @return String operationRef
+	 **/
+
+	String getOperationRef();
+
+	/**
+	 * sets this Link's operationRef property to the given operationRef.
+	 *
+	 * @param String operationRef
+	 */
+	void setOperationRef(String operationRef);
+
+	/**
+	 * sets this Link's operationRef property to the given operationRef and
+	 * returns this instance of Link
+	 *
+	 * @param String operationRef
+	 * @return Link
+	 */
+	Link operationRef(String operationRef);
+
+	/**
+	 * returns the requestBody property from a Link instance.
+	 *
+	 * @return RequestBody requestBody
+	 **/
+
+	RequestBody getRequestBody();
+
+	/**
+	 * sets this Link's requestBody property to the given requestBody.
+	 *
+	 * @param RequestBody requestBody
+	 */
+	void setRequestBody(RequestBody requestBody);
+
+	/**
+	 * sets this Link's requestBody property to the given requestBody and
+	 * returns this instance of Link
+	 *
+	 * @param RequestBody requestBody
+	 * @return Link
+	 */
+	Link requestBody(RequestBody requestBody);
+
+	/**
+	 * returns this Link's requestBody property for this instance of Link.
+	 *
+	 * @param String operationId
+	 */
+	String getOperationId();
+
+	/**
+	 * sets this Link's operationId property to the given operationId.
+	 *
+	 * @param String operationId
+	 */
+	void setOperationId(String operationId);
+
+	/**
+	 * sets this Link's operationId property to the given operationId and
+	 * returns this instance of Link
+	 *
+	 * @param String operationId
+	 * @return Link
+	 */
+	Link operationId(String operationId);
+
+	/**
+	 * returns the parameters property from a Link instance.
+	 *
+	 * @return LinkParameters parameters
+	 **/
+	Map<String, String> getParameters();
+
+	/**
+	 * sets this Link's parameters property to the given parameters.
+	 *
+	 * @param LinkParameters parameters
+	 */
+	void setParameters(Map<String, String> parameters);
+
+	/**
+	 * sets this Link's parameter property to the given parameter and
+	 * returns this instance of Link
+	 *
+	 * @param String name
+	 * @param String parameter
+	 * @return Link
+	 */
+	Link parameters(String name, String parameter);
+
+	/**
+	 * returns the headers property from a Link instance.
+	 *
+	 * @return Headers headers
+	 **/
+
+	Map<String, Header> getHeaders();
+
+	/**
+	 * sets this Link's headers property to the given headers.
+	 *
+	 * @param Map&lt;String, Header&gt; headers
+	 */
+	void setHeaders(Map<String, Header> headers);
+
+	/**
+	 * sets this Link's headers property to the given headers and
+	 * returns this instance of Link
+	 *
+	 * @param Map&lt;String, Header&gt; headers
+	 * @return Link
+	 */
+	Link headers(Map<String, Header> headers);
+
+	/**
+	 * Adds the given Header to this Link's map of headers, with the given name as its key.
+	 *
+	 * @param String name
+	 * @param Header header
+	 * @return Link
+	 */
+	Link addHeaderObject(String name, Header header);
+
+	/**
+	 * returns the description property from a Link instance.
+	 *
+	 * @return String description
+	 **/
+
+	String getDescription();
+
+	/**
+	 * returns the description property from a Link instance.
+	 *
+	 * @return String description
+	 **/
+	void setDescription(String description);
+
+	/**
+	 * sets this Link's description property to the given description and
+	 * returns this instance of Link
+	 *
+	 * @param String description
+	 * @return Link
+	 */
+	Link description(String description);
+
+	/**
+	 * returns the $ref property from a Link instance.
+	 *
+	 * @return String $ref
+	 **/
+	String get$ref();
+
+	/**
+	 * sets the $ref property for a Link instance.
+	 *
+	 * @param String $ref
+	 **/
+	void set$ref(String $ref);
+
+	/**
+	 * sets this Link's $ref property to the given description and
+	 * returns this instance of Link
+	 *
+	 * @param String $ref
+	 * @return Link
+	 */
+	Link $ref(String $ref);
+
+	/**
+	 * returns the extensions property from a Link instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds the given Object to this Link's map of extensions, with the given name as its key.
+	 *
+	 * @param String key
+	 * @param Object value
+	 */
+	void addExtension(String name, Object value);
+
+	/**
+	 * sets the extensions property for a Link instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/links/LinkParameter.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/links/LinkParameter.java
new file mode 100644
index 000000000..4b0a0e299
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/links/LinkParameter.java
@@ -0,0 +1,76 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.links;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * LinkParameter
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#linkOParametersbject"
+ */
+public interface LinkParameter extends Constructible {
+
+	/**
+	   * returns the value property from a LinkParameter instance.
+	   *
+	   * @return String value
+	   **/
+	String getValue();
+
+	/**
+	   * sets this LinkParameter's value property to the given value.
+	   *
+	   * @param String value
+	   */
+	void setValue(String value);
+
+	/**
+	   * sets this LinkParameter's value property to the given value and
+	   * returns this instance of LinkParameter
+	   *
+	   * @param String value
+	   * @return LinkParameter
+	   */
+	LinkParameter value(String value);
+
+	/**
+	   * returns the extensions property from a LinkParameter instance.
+	   *
+	   * @return Map&lt;String, Object&gt; extensions
+	   */
+	Map<String, Object> getExtensions();
+
+	/**
+	   * Adds the given Object to this LinkParameter's map of extensions, with the given key as its key.
+	   *
+	   * @param String key
+	   * @param Object value
+	   */
+	void addExtension(String name, Object value);
+
+	/**
+	   * sets the extensions property for a LinkParameter instance.
+	   *
+	   * @return Map&lt;String, Object&gt; extensions
+	   */
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/links/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/links/package-info.java
new file mode 100644
index 000000000..0e7b8780b
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/links/package-info.java
@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.openapi.models.links;
\ No newline at end of file
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
new file mode 100644
index 000000000..2fd4db669
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Content.java
@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * Content
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#contentObject"
+ */
+public interface Content extends Constructible, Map<String, MediaType> {
+
+	/**
+	 * Adds the MediaType for this Content, where name is the name of the MediaType and item is the MediaType itself
+	 *
+	 * @param String name
+	 * @param MediaType item
+	 * @return Content
+	 */
+	Content addMediaType(String name, MediaType item);
+
+}
\ No newline at end of file
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
new file mode 100644
index 000000000..2fd2e4210
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Discriminator.java
@@ -0,0 +1,81 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+public interface Discriminator extends Constructible {
+
+	/**
+	 * sets this Discriminator's propertyName property to the given propertyName and
+	 * returns this instance of Discriminator
+	 *
+	 * @param String propertyName
+	 * @return Discriminator
+	 */
+	Discriminator propertyName(String propertyName);
+
+	/**
+	 * returns the propertyName property from a Discriminator instance.
+	 *
+	 * @return String propertyName
+	 **/
+	String getPropertyName();
+
+	/**
+	 * sets this Discriminator's propertyName property to the given propertyName.
+	 *
+	 * @param String propertyName
+	 */
+	void setPropertyName(String propertyName);
+
+	/**
+	 * maps the given name to the given value and store it in this Discriminator's mapping property.
+	 * 
+	 * @param String name
+	 * @param String value
+	 * @return Discriminator
+	 */
+	Discriminator mapping(String name, String value);
+
+	/**
+	 * sets this Discriminator's mapping property to the given mapping and
+	 * returns this instance of Discriminator
+	 *
+	 * @param Map&lt;String, String&gt; mapping
+	 * @return Discriminator
+	 */
+	Discriminator mapping(Map<String, String> mapping);
+
+	/**
+	 * returns the mapping property from a Discriminator instance.
+	 *
+	 * @return Map&lt;String, String&gt; mapping
+	 **/
+	Map<String, String> getMapping();
+
+	/**
+	 * sets this Discriminator's mapping property to the given mapping.
+	 *
+	 * @param Map&lt;String, String&gt; mapping
+	 */
+	void setMapping(Map<String, String> mapping);
+
+}
\ No newline at end of file
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
new file mode 100644
index 000000000..52eb5b0b3
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Encoding.java
@@ -0,0 +1,187 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.headers.Header;
+
+/**
+ * Encoding
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#encodingObject"
+ */
+public interface Encoding extends Constructible {
+
+	enum StyleEnum {
+	    FORM("form"),
+	    SPACE_DELIMITED("spaceDelimited"),
+	    PIPE_DELIMITED("pipeDelimited"),
+	    DEEP_OBJECT("deepObject");
+	
+	    private String value;
+	
+	    StyleEnum(String value) {
+	        this.value = value;
+	    }
+	
+	    @Override
+	    public String toString() {
+	        return String.valueOf(value);
+	    }
+	}
+
+	/**
+	 * sets this Encoding's contentType property to the given contentType and
+	 * returns this instance of Encoding
+	 *
+	 * @param String contentType
+	 * @return Encoding
+	 */
+	Encoding contentType(String contentType);
+
+	/**
+	 * returns the contentType property from a Encoding instance.
+	 *
+	 * @return String contentType
+	 **/
+	String getContentType();
+
+	/**
+	 * sets this Encoding's contentType property to the given contentType.
+	 *
+	 * @param String contentType
+	 */
+	void setContentType(String contentType);
+
+	/**
+	 * sets this Encoding's headers property to the given headers and
+	 * returns this instance of Encoding
+	 *
+	 * @param Map&lt;String, Header&gt; headers
+	 * @return Encoding
+	 */
+	Encoding headers(Map<String, Header> headers);
+
+	/**
+	 * returns the headers property from a Encoding instance.
+	 *
+	 * @return Map&lt;String, Header&gt; headers
+	 **/
+	Map<String, Header> getHeaders();
+
+	/**
+	 * sets this Encoding's headers property to the given headers.
+	 *
+	 * @param Map&lt;String, Header&gt; headers
+	 */
+	void setHeaders(Map<String, Header> headers);
+
+	/**
+	 * sets this Encoding's style property to the given style and
+	 * returns this instance of Encoding
+	 *
+	 * @param String style
+	 * @return Encoding
+	 */
+	Encoding style(String style);
+
+	/**
+	 * returns the style property from a Encoding instance.
+	 *
+	 * @return String style
+	 **/
+	String getStyle();
+
+	/**
+	 * sets this Encoding's style property to the given style.
+	 *
+	 * @param String style
+	 */
+	void setStyle(String style);
+
+	/**
+	 * sets this Encoding's explode property to the given explode and
+	 * returns this instance of Encoding
+	 *
+	 * @param Boolean explode
+	 * @return Encoding
+	 */
+	Encoding explode(Boolean explode);
+
+	/**
+	 * returns the explode property from a Encoding instance.
+	 *
+	 * @return Boolean explode
+	 **/
+	Boolean getExplode();
+
+	/**
+	 * sets this Encoding's explode property to the given explode.
+	 *
+	 * @param Boolean explode
+	 */
+	void setExplode(Boolean explode);
+
+	/**
+	 * sets this Encoding's allowReserved property to the given allowReserved and
+	 * returns this instance of Encoding
+	 *
+	 * @param Boolean allowReserved
+	 * @return Encoding
+	 */
+	Encoding allowReserved(Boolean allowReserved);
+
+	/**
+	 * returns the allowReserved property from a Encoding instance.
+	 *
+	 * @return Boolean allowReserved
+	 **/
+	Boolean getAllowReserved();
+
+	/**
+	 * sets this Encoding's allowReserved property to the given allowReserved.
+	 *
+	 * @param Boolean allowReserved
+	 */
+	void setAllowReserved(Boolean allowReserved);
+
+	/**
+	 * returns the extensions property from a Encoding instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 **/
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds the given extension value to this Encoding's map of extensions, with the given name as its key.
+	 *
+	 * @param String name
+	 * @param Object value
+	 */
+	void addExtension(String name, Object value);
+
+	/**
+	 * sets this Encoding's extensions property to the given extensions.
+	 *
+	 * @param Map&lt;String, Object&gt; extensions
+	 */
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
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
new file mode 100644
index 000000000..fae5aca84
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MediaType.java
@@ -0,0 +1,198 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.examples.Example;
+
+/**
+ * MediaType
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#mediaTypeObject"
+ */
+public interface MediaType extends Constructible {
+
+	/**
+	 * returns the schema property from a MediaType instance.
+	 *
+	 * @return Schema schema
+	 **/
+
+	Schema getSchema();
+
+	/**
+	 * Sets schema field of a MediaType instance to the
+	 * parameter.
+	 *
+	 * @param schema
+	 */
+
+	void setSchema(Schema schema);
+
+	/**
+	 * Sets schema property of a MediaType instance to the
+	 * parameter and returns the instance.
+	 *
+	 * @param schema
+	 * @return MediaType instance with the set schema property
+	 */
+
+	MediaType schema(Schema schema);
+
+	/**
+	 * returns the examples map of String to Example from a MediaType instance.
+	 *
+	 * @return Map&lt;String, Example&gt; examples
+	 **/
+
+	Map<String, Example> getExamples();
+
+	/**
+	 * Sets examples field of a MediaType instance to the
+	 * parameter.
+	 *
+	 * @param examples
+	 */
+
+	void setExamples(Map<String, Example> examples);
+
+	/**
+	 * Sets examples field of a MediaType instance to the
+	 * parameter and returns the instance.
+	 *
+	 * @param examples
+	 * @return MediaType instance with the set examples property
+	 */
+
+	MediaType examples(Map<String, Example> examples);
+
+	/**
+	 * Adds an example item to examples map of a MediaType instance
+	 * and returns the instance.
+	 * <p>
+	 * If the examples property is null, creates a new HashMap
+	 * and adds the item to it.
+	 *
+	 * @param key
+	 * @param examplesItem
+	 * @return MediaType instance with the set example item
+	 */
+
+	MediaType addExamples(String key, Example examplesItem);
+
+	/**
+	 * returns the example property from a MediaType instance.
+	 *
+	 * @return String example
+	 **/
+
+	String getExample();
+
+	/**
+	 * Sets example property of a MediaType instance to the
+	 * parameter.
+	 *
+	 * @param example
+	 */
+
+	void setExample(String example);
+
+	/**
+	 * Sets example property of a MediaType instance to the
+	 * parameter and returns the instance.
+	 *
+	 * @param example
+	 * @return MediaType instance with the set example property
+	 */
+
+	MediaType example(String example);
+
+	/**
+	 * returns the encoding property from a MediaType instance.
+	 *
+	 * @return Encoding encoding
+	 **/
+
+	Map<String, Encoding> getEncoding();
+
+	/**
+	 * Sets encoding property of a MediaType instance to the
+	 * parameter.
+	 *
+	 * @param encoding
+	 */
+
+	void setEncoding(Map<String, Encoding> encoding);
+
+	/**
+	 * Sets encoding property of a MediaType instance to the
+	 * parameter and returns the instance.
+	 *
+	 * @param encoding
+	 * @return MediaType instance with the set encoding property
+	 */
+
+	MediaType encoding(Map<String, Encoding> encoding);
+
+	/**
+	 * Adds an Encoding item to encoding map of a MediaType instance
+	 * and returns the instance.
+	 * <p>
+	 * If the encoding property is null, creates a new HashMap
+	 * and adds the item to it.
+	 *
+	 * @param String key
+	 * @param Encoding encodingItem
+	 * @return MediaType instance with the added encoding item
+	 */
+
+	MediaType addEncoding(String key, Encoding encodingItem);
+
+	/**
+	 * Returns extensions property of a MediaType instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+
+	java.util.Map<String, Object> getExtensions();
+
+	/**
+	 * Adds an object item to extensions map for
+	 * the specified name key.
+	 * <p>
+	 * If the extensions property is null, creates a new HashMap
+	 * and adds the item to it.
+	 *
+	 * @param name - map key
+	 * @param value - map value
+	 */
+
+	void addExtension(String name, Object value);
+
+	/**
+	 * Sets extensions property of a MediaType instance
+	 * to the parameter.
+	 *
+	 * @param extensions
+	 */
+
+	void setExtensions(java.util.Map<String, Object> extensions);
+
+}
\ No newline at end of file
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
new file mode 100644
index 000000000..12811eef3
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java
@@ -0,0 +1,977 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.math.BigDecimal;
+import java.util.List;
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.ExternalDocumentation;
+
+/**
+ * Schema
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#schemaObject"
+ */
+public interface Schema<T> extends Constructible {
+
+	/**
+	 * returns the name property from a from a Schema instance. Ignored in serialization.
+	 *
+	 * @return String name
+	 **/
+	String getName();
+
+	/**
+	 * Sets the name property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param name
+	 */
+
+	void setName(String name);
+
+	/**
+	 * Sets the name property of a Schema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param name
+	 * @return Schema instance with the modified name property
+	 */
+
+	Schema name(String name);
+
+	/**
+	 * returns the discriminator property from a Schema instance.
+	 *
+	 * @return Discriminator discriminator
+	 **/
+
+	Discriminator getDiscriminator();
+
+	/**
+	 * Sets discriminator property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param discriminator
+	 */
+
+	void setDiscriminator(Discriminator discriminator);
+
+	/**
+	 * Sets discriminator property of a Schema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param discriminator
+	 * @return Schema instance with the modified discriminator.
+	 */
+
+	Schema discriminator(Discriminator discriminator);
+
+	/**
+	 * returns the title property from a Schema instance.
+	 *
+	 * @return String title
+	 **/
+
+	String getTitle();
+
+	/**
+	 * Sets the title property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param title
+	 */
+
+	void setTitle(String title);
+
+	/**
+	 * Sets the title property of a Schema instance
+	 * to the parameter and returns the modified instance.
+	 *
+	 * @param title
+	 * @return Schema instance with the modified title.
+	 */
+
+	Schema title(String title);
+
+	/**
+	 * returns the _default property from a StringSchema instance.
+	 *
+	 * @return String _default
+	 **/
+
+	T getDefault();
+
+	/**
+	 * Set _default property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param _default
+	 */
+
+	void setDefault(Object _default);
+
+	/**
+	 * Returns _enum property for a Schema instance.
+	 *
+	 * @return List&lt;T&gt; _enum
+	 */
+
+	List<T> getEnum();
+
+	/**
+	 * Sets _enum property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param _enum
+	 */
+
+	void setEnum(List<T> _enum);
+
+	/**
+	 * Adds a generic type T item to _enum of a Schema instance.
+	 *
+	 * @param _enumItem
+	 */
+
+	void addEnumItemObject(T _enumItem);
+
+	/**
+	 * returns the multipleOf property from a Schema instance.
+	 * <p>
+	 * minimum: 0
+	 *
+	 * @return BigDecimal multipleOf
+	 **/
+
+	BigDecimal getMultipleOf();
+
+	/**
+	 * Sets multipleOf property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param multipleOf
+	 */
+
+	void setMultipleOf(BigDecimal multipleOf);
+
+	/**
+	 * Sets multipleOf property of a Schema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param multipleOf
+	 * @return Schema instance with the modified multipleOf property
+	 */
+
+	Schema multipleOf(BigDecimal multipleOf);
+
+	/**
+	 * returns the maximum property from a Schema instance.
+	 *
+	 * @return BigDecimal maximum
+	 **/
+
+	BigDecimal getMaximum();
+
+	/**
+	 * Sets maximum property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param maximum
+	 */
+
+	void setMaximum(BigDecimal maximum);
+
+	/**
+	 * Sets maximum property of a Schema instance to the parameter
+	 * and returns the instance.
+	 *
+	 * @param maximum
+	 * @return Schema instance with the modified maximum property
+	 */
+
+	Schema maximum(BigDecimal maximum);
+
+	/**
+	 * returns the exclusiveMaximum property from a Schema instance.
+	 *
+	 * @return Boolean exclusiveMaximum
+	 **/
+
+	Boolean getExclusiveMaximum();
+
+	/**
+	 * Sets exclusiveMaximum property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param exclusiveMaximum
+	 */
+
+	void setExclusiveMaximum(Boolean exclusiveMaximum);
+
+	/**
+	 * Sets exclusiveMaximum property of a Schema instance to the parameter
+	 * and returns the instance.
+	 *
+	 * @param exclusiveMaximum
+	 * @return Schema instance with modified exclusiveMaximum property.
+	 */
+
+	Schema exclusiveMaximum(Boolean exclusiveMaximum);
+
+	/**
+	 * returns the minimum property from a Schema instance.
+	 *
+	 * @return BigDecimal minimum
+	 **/
+
+	BigDecimal getMinimum();
+
+	/**
+	 * Sets minimum property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param minimum
+	 */
+
+	void setMinimum(BigDecimal minimum);
+
+	/**
+	 * Sets minimum property of a Schema instance
+	 * to the parameter and returns the instance
+	 *
+	 * @param minimum
+	 * @return Schema instance with the modified minimum property.
+	 */
+
+	Schema minimum(BigDecimal minimum);
+
+	/**
+	 * returns the exclusiveMinimum property from a Schema instance.
+	 *
+	 * @return Boolean exclusiveMinimum
+	 **/
+
+	Boolean getExclusiveMinimum();
+
+	/**
+	 * Sets exclusiveMinimum property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param exclusiveMinimum
+	 */
+
+	void setExclusiveMinimum(Boolean exclusiveMinimum);
+
+	/**
+	 * Sets exclusiveMinimum property of a Schema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param exclusiveMinimum
+	 * @return Schema instance with the modified exclusiveMinimum property.
+	 */
+
+	Schema exclusiveMinimum(Boolean exclusiveMinimum);
+
+	/**
+	 * returns the maxLength property from a Schema instance.
+	 * <p>
+	 * minimum: 0
+	 *
+	 * @return Integer maxLength
+	 **/
+
+	Integer getMaxLength();
+
+	/**
+	 * Sets maxLength property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param maxLength
+	 */
+
+	void setMaxLength(Integer maxLength);
+
+	/**
+	 * Sets maxLength property of a Schema instance
+	 * to the parameter and returns the instance
+	 *
+	 * @param maxLength
+	 * @return Schema instance with the modified maxLength property.
+	 */
+
+	Schema maxLength(Integer maxLength);
+
+	/**
+	 * returns the minLength property from a Schema instance.
+	 * <p>
+	 * minimum: 0
+	 *
+	 * @return Integer minLength
+	 **/
+
+	Integer getMinLength();
+
+	/**
+	 * Sets minLength property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param minLength
+	 */
+
+	void setMinLength(Integer minLength);
+
+	/**
+	 * Sets minLength property of a Schema instance
+	 * to the parameter and returns the instance
+	 *
+	 * @param minLength
+	 * @return Schema instance with the modified minLength property.
+	 */
+
+	Schema minLength(Integer minLength);
+
+	/**
+	 * returns the pattern property from a Schema instance.
+	 *
+	 * @return String pattern
+	 **/
+
+	String getPattern();
+
+	/**
+	 * Sets pattern property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param pattern
+	 */
+
+	void setPattern(String pattern);
+
+	/**
+	 * Sets pattern property of a Schema instance
+	 * to the parameter and returns the instance
+	 *
+	 * @param pattern
+	 * @return Schema instance with the modified pattern property.
+	 */
+
+	Schema pattern(String pattern);
+
+	/**
+	 * returns the maxItems property from a Schema instance.
+	 * <p>
+	 * minimum: 0
+	 *
+	 * @return Integer maxItems
+	 **/
+
+	Integer getMaxItems();
+
+	/**
+	 * Sets maxItems property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param maxItems
+	 */
+
+	void setMaxItems(Integer maxItems);
+
+	/**
+	 * Sets maxItems property of a Schema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param maxItems
+	 * @return Schema instance with the modified maxItems property.
+	 */
+
+	Schema maxItems(Integer maxItems);
+
+	/**
+	 * returns the minItems property from a Schema instance.
+	 * <p>
+	 * minimum: 0
+	 *
+	 * @return Integer minItems
+	 **/
+
+	Integer getMinItems();
+
+	/**
+	 * Sets minItems property of Schema instance
+	 * to the parameter.
+	 *
+	 * @param minItems
+	 */
+
+	void setMinItems(Integer minItems);
+
+	/**
+	 * Sets minItems property of a Schema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param minItems
+	 * @return Schema instance with the modified minItems property.
+	 */
+
+	Schema minItems(Integer minItems);
+
+	/**
+	 * returns the uniqueItems property from a Schema instance.
+	 *
+	 * @return Boolean uniqueItems
+	 **/
+
+	Boolean getUniqueItems();
+
+	/**
+	 * Sets uniqueItems property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param uniqueItems
+	 */
+
+	void setUniqueItems(Boolean uniqueItems);
+
+	/**
+	 * Sets uniqueItems property of a Schema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param uniqueItems
+	 * @return Schema instance with the modified uniqueItems property.
+	 */
+
+	Schema uniqueItems(Boolean uniqueItems);
+
+	/**
+	 * returns the maxProperties property from a Schema instance.
+	 * <p>
+	 * minimum: 0
+	 *
+	 * @return Integer maxProperties
+	 **/
+
+	Integer getMaxProperties();
+
+	/**
+	 * Sets maxProperties property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param maxProperties
+	 */
+
+	void setMaxProperties(Integer maxProperties);
+
+	/**
+	 * Sets maxProperties property of a Schema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param maxProperties
+	 * @return Schema instance with the modified maxProperty property.
+	 */
+
+	Schema maxProperties(Integer maxProperties);
+
+	/**
+	 * returns the minProperties property from a Schema instance.
+	 * <p>
+	 * minimum: 0
+	 *
+	 * @return Integer minProperties
+	 **/
+
+	Integer getMinProperties();
+
+	/**
+	 * Sets minProperties property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param minProperties
+	 */
+
+	void setMinProperties(Integer minProperties);
+
+	/**
+	 * Sets minProperties property of a Schema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param minProperties
+	 * @return Schema instance with the modified minProperty property.
+	 */
+
+	Schema minProperties(Integer minProperties);
+
+	/**
+	 * returns the required property from a Schema instance.
+	 *
+	 * @return List&lt;String&gt; required
+	 **/
+
+	List<String> getRequired();
+
+	/**
+	 * Sets required property of a Schema instance if
+	 * it is null or does not contain the List items
+	 * passed in as method arguments.
+	 *
+	 * @param required
+	 */
+
+	void setRequired(List<String> required);
+
+	/**
+	 * Sets required List property of a Schema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param required
+	 * @return Schema instance with the set required property.
+	 */
+
+	Schema required(List<String> required);
+
+	/**
+	 * Adds an item to required List of a Schema instance.
+	 * Creates new ArrayList if instance's required property is null.
+	 *
+	 * @param requiredItem
+	 * @return Schema instance with added required item.
+	 */
+
+	Schema addRequiredItem(String requiredItem);
+
+	/**
+	 * returns the type property from a Schema instance.
+	 *
+	 * @return String type
+	 **/
+
+	String getType();
+
+	/**
+	 * Sets the type property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param type
+	 */
+
+	void setType(String type);
+
+	/**
+	 * Sets the type property of a Schema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param type
+	 * @return Schema instance with the modified type property.
+	 */
+
+	Schema type(String type);
+
+	/**
+	 * returns the not property from a Schema instance.
+	 *
+	 * @return Schema not
+	 **/
+
+	Schema getNot();
+
+	/**
+	 * Sets the not property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param not
+	 */
+
+	void setNot(Schema not);
+
+	/**
+	 * Sets the not property of a Schema instance
+	 * to the parameter and
+	 * returns the instance.
+	 *
+	 * @param not
+	 * @return Schema with the modified not property.
+	 */
+
+	Schema not(Schema not);
+
+	/**
+	 * returns the properties property from a Schema instance.
+	 *
+	 * @return Map&lt;String, Schema&gt; properties
+	 **/
+
+	Map<String, Schema> getProperties();
+
+	/**
+	 * Sets properties property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param properties
+	 */
+
+	void setProperties(Map<String, Schema> properties);
+
+	/**
+	 * Sets properties property of a Schema instance
+	 * to the parameter and returns the modified instance.
+	 *
+	 * @param properties
+	 * @return Schema instance with the set properties property.
+	 */
+
+	Schema properties(Map<String, Schema> properties);
+
+	/**
+	 * Adds a Schema property item at specified key to properties
+	 * property of a Schema instance and returns the instance.
+	 *
+	 * @param key
+	 * @param propertiesItem
+	 * @return Schema instance with added property item.
+	 */
+
+	Schema addProperties(String key, Schema propertiesItem);
+
+	/**
+	 * returns the additionalProperties property from a Schema instance.
+	 *
+	 * @return Schema additionalProperties
+	 **/
+
+	Schema getAdditionalProperties();
+
+	/**
+	 * Sets additionalProperties property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param additionalProperties
+	 */
+
+	void setAdditionalProperties(Schema additionalProperties);
+
+	/**
+	 * Sets additionalProperties property of a Schema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param additionalProperties
+	 * @return Schema instance with the set additionalProperties property
+	 */
+
+	Schema additionalProperties(Schema additionalProperties);
+
+	/**
+	 * returns the description property from a Schema instance.
+	 *
+	 * @return String description
+	 **/
+
+	String getDescription();
+
+	/**
+	 * Sets description property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param description
+	 */
+
+	void setDescription(String description);
+
+	/**
+	 * Sets description property of a Schema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param description
+	 * @return Schema instance with the set description property
+	 */
+
+	Schema description(String description);
+
+	/**
+	 * returns the format property from a Schema instance.
+	 *
+	 * @return String format
+	 **/
+
+	String getFormat();
+
+	/**
+	 * Sets format property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param format
+	 */
+
+	void setFormat(String format);
+
+	/**
+	 * Sets format property of a Schema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param format
+	 * @return Schema instance with the set format property.
+	 */
+
+	Schema format(String format);
+
+	/**
+	 * returns the $ref property from a Schema instance.
+	 *
+	 * @return String $ref
+	 **/
+	String get$ref();
+
+	/**
+	 * Set $ref property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param $ref
+	 */
+
+	void set$ref(String $ref);
+
+	/**
+	 * Set $ref property of a Schema instance
+	 * to the parameter and return the instance.
+	 *
+	 * @param $ref
+	 * @return Schema instance with the set $ref property.
+	 */
+
+	Schema $ref(String $ref);
+
+	/**
+	 * returns the nullable property from a Schema instance.
+	 *
+	 * @return Boolean nullable
+	 **/
+
+	Boolean getNullable();
+
+	/**
+	 * Sets nullable property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param nullable
+	 */
+
+	void setNullable(Boolean nullable);
+
+	/**
+	 * Sets nullable property of a Schema instance
+	 * to the parameter and return the instance.
+	 *
+	 * @param nullable
+	 * @return Schema instance with the set nullable property.
+	 */
+
+	Schema nullable(Boolean nullable);
+
+	/**
+	 * returns the readOnly property from a Schema instance.
+	 *
+	 * @return Boolean readOnly
+	 **/
+
+	Boolean getReadOnly();
+
+	/**
+	 * Sets readOnly property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param readOnly
+	 */
+
+	void setReadOnly(Boolean readOnly);
+
+	/**
+	 * Sets readOnly property of a Schema instance
+	 * to the parameter and return the instance.
+	 *
+	 * @param readOnly
+	 * @return Schema instance with the set readOnly property.
+	 */
+
+	Schema readOnly(Boolean readOnly);
+
+	/**
+	 * returns the writeOnly property from a Schema instance.
+	 *
+	 * @return Boolean writeOnly
+	 **/
+
+	Boolean getWriteOnly();
+
+	/**
+	 * Sets writeOnly property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param writeOnly
+	 */
+
+	void setWriteOnly(Boolean writeOnly);
+
+	/**
+	 * Sets writeOnly property of a Schema instance
+	 * to the parameter and return the instance.
+	 *
+	 * @param writeOnly
+	 * @return Schema instance with the set writeOnly property.
+	 */
+
+	Schema writeOnly(Boolean writeOnly);
+
+	/**
+	 * returns the example property from a Schema instance.
+	 *
+	 * @return String example
+	 **/
+
+	Object getExample();
+
+	/**
+	 * Sets example property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param example
+	 */
+
+	void setExample(Object example);
+
+	/**
+	 * Sets example property of a Schema instance
+	 * to the parameter and return the instance.
+	 *
+	 * @param example
+	 * @return Schema instance with the set example property.
+	 */
+
+	Schema example(Object example);
+
+	/**
+	 * returns the externalDocs property from a Schema instance.
+	 *
+	 * @return ExternalDocumentation externalDocs
+	 **/
+
+	ExternalDocumentation getExternalDocs();
+
+	/**
+	 * Sets externalDocs property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param externalDocs
+	 */
+
+	void setExternalDocs(ExternalDocumentation externalDocs);
+
+	/**
+	 * Sets externalDocs property of a Schema instance
+	 * to the parameter and
+	 * return the instance.
+	 *
+	 * @param externalDocs
+	 * @return Schema instance with the set externalDocs property
+	 */
+
+	Schema externalDocs(ExternalDocumentation externalDocs);
+
+	/**
+	 * returns the deprecated property from a Schema instance.
+	 *
+	 * @return Boolean deprecated
+	 **/
+
+	Boolean getDeprecated();
+
+	/**
+	 * Sets deprecated property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param deprecated
+	 */
+
+	void setDeprecated(Boolean deprecated);
+
+	/**
+	 * Sets deprecated property of a Schema instance
+	 * to the parameter and
+	 * return the instance.
+	 *
+	 * @param deprecated
+	 * @return Schema instance with the set deprecated property
+	 */
+
+	Schema deprecated(Boolean deprecated);
+
+	/**
+	 * returns the xml property from a Schema instance.
+	 *
+	 * @return XML xml
+	 **/
+
+	XML getXml();
+
+	/**
+	 * Sets xml property of a Schema instance
+	 * to the parameter.
+	 *
+	 * @param xml
+	 */
+
+	void setXml(XML xml);
+
+	/**
+	 * Sets xml property of a Schema instance
+	 * to the parameter and
+	 * return the instance.
+	 *
+	 * @param xml
+	 * @return Schema instance with the set xml property
+	 */
+
+	Schema xml(XML xml);
+
+	/**
+	 * Returns extensions property of a Schema instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds an object item to extensions map at
+	 * the specified key.
+	 *
+	 * @param name - map key
+	 * @param value - map value
+	 */
+
+	void addExtension(String name, Object value);
+
+	/**
+	 * Sets extensions property of a Schema instance
+	 *
+	 * @param extensions
+	 */
+
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java
new file mode 100644
index 000000000..4f13f123e
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java
@@ -0,0 +1,193 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * XML
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#xmlObject"
+ */
+public interface XML extends Constructible {
+
+	/**
+	 * returns the name property from a XML instance.
+	 *
+	 * @return String name
+	 **/
+
+	String getName();
+
+	/**
+	 * Sets the name property of an XML instance
+	 * to the parameter.
+	 *
+	 * @param name
+	 */
+
+	void setName(String name);
+
+	/**
+	 * Sets the name property of an XML instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param name
+	 * @return XML instance with the set name property
+	 */
+
+	XML name(String name);
+
+	/**
+	 * returns the namespace property from a XML instance.
+	 *
+	 * @return String namespace
+	 **/
+
+	String getNamespace();
+
+	/**
+	 * Sets the namespace property of an XML instance
+	 * to the parameter.
+	 *
+	 * @param namespace
+	 */
+
+	void setNamespace(String namespace);
+
+	/**
+	 * Sets the namespace property of an XML instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param namespace
+	 * @return XML instance with the set namespace property
+	 */
+
+	XML namespace(String namespace);
+
+	/**
+	 * returns the prefix property from a XML instance.
+	 *
+	 * @return String prefix
+	 **/
+
+	String getPrefix();
+
+	/**
+	 * Sets the prefix property of an XML instance
+	 * to the parameter.
+	 *
+	 * @param prefix
+	 */
+
+	void setPrefix(String prefix);
+
+	/**
+	 * Sets the prefix property of an XML instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param prefix
+	 * @return XML instance with the set prefix property
+	 */
+
+	XML prefix(String prefix);
+
+	/**
+	 * returns the attribute property from a XML instance.
+	 *
+	 * @return Boolean attribute
+	 **/
+
+	Boolean getAttribute();
+
+	/**
+	 * Sets the attribute property of an XML instance
+	 * to the parameter.
+	 *
+	 * @param attribute
+	 */
+
+	void setAttribute(Boolean attribute);
+
+	/**
+	 * Sets the attribute property of an XML instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param attribute
+	 * @return XML instance with the set attribute property
+	 */
+
+	XML attribute(Boolean attribute);
+
+	/**
+	 * returns the wrapped property from a XML instance.
+	 *
+	 * @return Boolean wrapped
+	 **/
+
+	Boolean getWrapped();
+
+	/**
+	 * Sets the wrapped property of an XML instance
+	 * to the parameter.
+	 *
+	 * @param wrapped
+	 */
+
+	void setWrapped(Boolean wrapped);
+
+	/**
+	 * Sets the wrapped property of an XML instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param wrapped
+	 * @return XML instance with the set wrapped property
+	 */
+
+	XML wrapped(Boolean wrapped);
+
+	/**
+	 * Returns the extensions property of an XML instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds an item to the extensions property of an XML instance.
+	 * If extensions is null, creates a HashMap and adds item to it.
+	 *
+	 * @param name - map key
+	 * @param value - map value
+	 */
+
+	void addExtension(String name, Object value);
+
+	/**
+	 * Sets the extensions property of an XML instance
+	 * to the parameter.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/package-info.java
new file mode 100644
index 000000000..ea4de6e3a
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/package-info.java
@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.openapi.models.media;
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/package-info.java
new file mode 100644
index 000000000..773eedc41
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/package-info.java
@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.openapi.models;
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/CookieParameter.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/CookieParameter.java
new file mode 100644
index 000000000..60c050cc2
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/CookieParameter.java
@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.parameters;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * CookieParameter
+ */
+public interface CookieParameter extends Constructible, Parameter {
+
+}
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/HeaderParameter.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/HeaderParameter.java
new file mode 100644
index 000000000..4fe2d4860
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/HeaderParameter.java
@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.parameters;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * HeaderParameter
+ */
+public interface HeaderParameter extends Constructible, Parameter {
+
+}
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
new file mode 100644
index 000000000..4996aba56
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/Parameter.java
@@ -0,0 +1,470 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.parameters;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.examples.Example;
+import org.eclipse.microprofile.openapi.models.media.Content;
+import org.eclipse.microprofile.openapi.models.media.Schema;
+
+/**
+ * Parameter
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#parameterObject"
+ */
+public interface Parameter {
+
+	/**
+	 * Gets or Sets style
+	 */
+	enum StyleEnum {
+	    MATRIX("matrix"),
+	    LABEL("label"),
+	    FORM("form"),
+	    SIMPLE("simple"),
+	    SPACEDELIMITED("spaceDelimited"),
+	    PIPEDELIMITED("pipeDelimited"),
+	    DEEPOBJECT("deepObject");
+	
+	    private final String value;
+	
+	    StyleEnum(String value) {
+	        this.value = value;
+	    }
+	
+	    @Override
+	    public String toString() {
+	        return String.valueOf(value);
+	    }
+	}
+
+	/**
+	 * returns the name property from a Parameter instance.
+	 *
+	 * @return String name
+	 **/
+
+	String getName();
+
+	/**
+	 * Sets the name property of a Parameter instance
+	 * to the parameter.
+	 *
+	 * @param name
+	 */
+
+	void setName(String name);
+
+	/**
+	 * Sets the name property of a Parameter instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param name
+	 * @return Parameter instance with the modified name property
+	 */
+
+	Parameter name(String name);
+
+	/**
+	 * returns the in property from a Parameter instance.
+	 *
+	 * @return String in
+	 **/
+
+	String getIn();
+
+	/**
+	 * Sets the in property of a Parameter instance
+	 * to the parameter.
+	 * If in property is set to path then also sets
+	 * required property to true.
+	 *
+	 * @param in
+	 */
+
+	void setIn(String in);
+
+	/**
+	 * Sets the in property of a Parameter instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param in
+	 * @return Parameter instance with the modified in property
+	 */
+
+	Parameter in(String in);
+
+	/**
+	 * returns the description property from a Parameter instance.
+	 *
+	 * @return String description
+	 **/
+
+	String getDescription();
+
+	/**
+	 * Sets the description property of a Parameter instance
+	 * to the parameter.
+	 *
+	 * @param description
+	 */
+
+	void setDescription(String description);
+
+	/**
+	 * Sets the description property of a Parameter instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param description
+	 * @return Parameter instance with the modified description property
+	 */
+
+	Parameter description(String description);
+
+	/**
+	 * returns the required property from a Parameter instance.
+	 *
+	 * @return Boolean required
+	 **/
+
+	Boolean getRequired();
+
+	/**
+	 * Sets the required property of a Parameter instance
+	 * to the parameter.
+	 *
+	 * @param required
+	 */
+
+	void setRequired(Boolean required);
+
+	/**
+	 * Sets the required property of a Parameter instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param required
+	 * @return Parameter instance with the modified required property
+	 */
+
+	Parameter required(Boolean required);
+
+	/**
+	 * returns the deprecated property from a Parameter instance.
+	 *
+	 * @return Boolean deprecated
+	 **/
+
+	Boolean getDeprecated();
+
+	/**
+	 * Sets the deprecated property of a Parameter instance
+	 * to the parameter.
+	 *
+	 * @param deprecated
+	 */
+
+	void setDeprecated(Boolean deprecated);
+
+	/**
+	 * Sets the deprecated property of a Parameter instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param deprecated
+	 * @return Parameter instance with the modified deprecated property
+	 */
+
+	Parameter deprecated(Boolean deprecated);
+
+	/**
+	 * returns the allowEmptyValue property from a Parameter instance.
+	 *
+	 * @return Boolean allowEmptyValue
+	 **/
+
+	Boolean getAllowEmptyValue();
+
+	/**
+	 * Sets the allowEmptyValue property of a Parameter instance
+	 * to the parameter.
+	 *
+	 * @param allowEmptyValue
+	 */
+
+	void setAllowEmptyValue(Boolean allowEmptyValue);
+
+	/**
+	 * Sets the allowEmptyValue property of a Parameter instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param allowEmptyValue
+	 * @return Parameter instance with the modified allowEmptyValue property
+	 */
+
+	Parameter allowEmptyValue(Boolean allowEmptyValue);
+
+	/**
+	 * returns the style property from a Parameter instance.
+	 *
+	 * @return StyleEnum style
+	 **/
+
+	Parameter.StyleEnum getStyle();
+
+	/**
+	 * Sets the style property of a Parameter instance
+	 * to the parameter.
+	 *
+	 * @param style
+	 */
+
+	void setStyle(Parameter.StyleEnum style);
+
+	/**
+	 * Sets the style property of a Parameter instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param style
+	 * @return Parameter instance with the modified style property
+	 */
+
+	Parameter style(Parameter.StyleEnum style);
+
+	/**
+	 * returns the explode property from a Parameter instance.
+	 *
+	 * @return Boolean explode
+	 **/
+
+	Boolean getExplode();
+
+	/**
+	 * Sets the explode property of a Parameter instance
+	 * to the parameter.
+	 *
+	 * @param explode
+	 */
+
+	void setExplode(Boolean explode);
+
+	/**
+	 * Sets the explode property of a Parameter instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param explode
+	 * @return Parameter instance with the modified explode property
+	 */
+
+	Parameter explode(Boolean explode);
+
+	/**
+	 * returns the allowReserved property from a Parameter instance.
+	 *
+	 * @return Boolean allowReserved
+	 **/
+
+	Boolean getAllowReserved();
+
+	/**
+	 * Sets the allowReserved property of a Parameter instance
+	 * to the parameter.
+	 *
+	 * @param allowReserved
+	 */
+
+	void setAllowReserved(Boolean allowReserved);
+
+	/**
+	 * Sets the allowReserved property of a Parameter instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param allowReserved
+	 * @return Parameter instance with the modified allowReserved property
+	 */
+
+	Parameter allowReserved(Boolean allowReserved);
+
+	/**
+	 * returns the schema property from a Parameter instance.
+	 *
+	 * @return Schema schema
+	 **/
+
+	Schema getSchema();
+
+	/**
+	 * Sets the schema property of a Parameter instance
+	 * to the parameter.
+	 *
+	 * @param schema
+	 */
+
+	void setSchema(Schema schema);
+
+	/**
+	 * Sets the schema property of a Parameter instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param schema
+	 * @return Parameter instance with the modified schema property
+	 */
+
+	Parameter schema(Schema schema);
+
+	/**
+	 * returns the examples property from a Parameter instance.
+	 *
+	 * @return Map&lt;String, Example&gt; examples
+	 **/
+
+	Map<String, Example> getExamples();
+
+	void setExamples(Map<String, Example> examples);
+
+	/**
+	 * Sets the examples property of a Parameter instance
+	 * to the parameter.
+	 *
+	 * @param examples
+	 */
+
+	Parameter examples(Map<String, Example> examples);
+
+	/**
+	 * Adds an example item to the examples property of a Parameter instance
+	 * at the specified key and returns the instance.
+	 * If examples is null, creates a new HashMap and adds item
+	 *
+	 * @param key
+	 * @param examplesItem
+	 * @return Parameter instance with the added example item
+	 */
+
+	Parameter addExamples(String key, Example examplesItem);
+
+	/**
+	 * returns the example property from a Parameter instance.
+	 *
+	 * @return String example
+	 **/
+
+	String getExample();
+
+	/**
+	 * Sets the example property of a Parameter instance
+	 * to the parameter.
+	 *
+	 * @param example
+	 */
+
+	void setExample(String example);
+
+	/**
+	 * Sets the example property of a Parameter instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param example
+	 * @return Parameter instance with the modified example property
+	 */
+
+	Parameter example(String example);
+
+	/**
+	 * returns the content property from a Parameter instance.
+	 *
+	 * @return Content content
+	 **/
+
+	Content getContent();
+
+	/**
+	 * Sets the content property of a Parameter instance
+	 * to the parameter.
+	 *
+	 * @param content
+	 */
+
+	void setContent(Content content);
+
+	/**
+	 * Sets the content property of a Parameter instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param content
+	 * @return Parameter instance with the modified content property
+	 */
+
+	Parameter content(Content content);
+
+	/**
+	 * returns the $ref property from a Parameter instance.
+	 *
+	 * @return String $ref
+	 **/
+
+	String get$ref();
+
+	/**
+	 * Sets $ref property of a Parameter instance
+	 * to the parameter.
+	 *
+	 * @param $ref
+	 */
+
+	void set$ref(String $ref);
+
+	/**
+	 * Sets $ref property of a Parameter instance
+	 * to the parameter and return the instance.
+	 *
+	 * @param $ref
+	 * @return Parameter instance with the set $ref property.
+	 */
+
+	Parameter $ref(String $ref);
+
+	/**
+	 * Returns extensions property of a Parameter instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds an object item to extensions map at
+	 * the specified key.
+	 * <p>
+	 * If extensions is null, creates a new HashMap
+	 * and adds item to it
+	 *
+	 * @param String name - map key
+	 * @param Object value - map value
+	 */
+
+	void addExtension(String name, Object value);
+
+	/**
+	 * Sets extensions property of a Parameter instance
+	 *
+	 * @param Map&lt;String, Object&gt; extensions
+	 */
+
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/PathParameter.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/PathParameter.java
new file mode 100644
index 000000000..51a5d7a30
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/PathParameter.java
@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.parameters;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * PathParameter
+ */
+public interface PathParameter extends Constructible, Parameter {
+
+}
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/QueryParameter.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/QueryParameter.java
new file mode 100644
index 000000000..37da1a1f2
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/QueryParameter.java
@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.parameters;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * QueryParameter
+ */
+public interface QueryParameter extends Constructible, Parameter {
+
+}
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java
new file mode 100644
index 000000000..29c1a4b67
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java
@@ -0,0 +1,167 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.parameters;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.media.Content;
+
+/**
+ * RequestBody
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#requestBodyObject"
+ */
+public interface RequestBody extends Constructible {
+
+	/**
+	 * returns the description property from a RequestBody instance.
+	 *
+	 * @return String description
+	 **/
+
+	String getDescription();
+
+	/**
+	 * Sets the description property of a RequestBody instance
+	 * to the parameter.
+	 *
+	 * @param description
+	 */
+
+	void setDescription(String description);
+
+	/**
+	 * Sets the description property of a RequestBody instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param description
+	 * @return RequestBody instance with the modified description property
+	 */
+
+	RequestBody description(String description);
+
+	/**
+	 * returns the content property from a RequestBody instance.
+	 *
+	 * @return Content content
+	 **/
+
+	Content getContent();
+
+	/**
+	 * Sets the content property of a RequestBody instance
+	 * to the parameter.
+	 *
+	 * @param content
+	 */
+
+	void setContent(Content content);
+
+	/**
+	 * Sets the content property of a RequestBody instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param content
+	 * @return RequestBody instance with the modified content property
+	 */
+
+	RequestBody content(Content content);
+
+	/**
+	 * returns the required property from a RequestBody instance.
+	 *
+	 * @return Boolean required
+	 **/
+
+	Boolean getRequired();
+
+	/**
+	 * Sets the required property of a RequestBody instance
+	 * to the parameter.
+	 *
+	 * @param required
+	 */
+
+	void setRequired(Boolean required);
+
+	/**
+	 * Sets the required property of a RequestBody instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param required
+	 * @return RequestBody instance with the modified required property
+	 */
+
+	RequestBody required(Boolean required);
+
+	/**
+	 * Returns extensions property of a RequestBody instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds an object item to extensions map at
+	 * the specified key.
+	 *
+	 * @param name - map key
+	 * @param value - map value
+	 */
+
+	void addExtension(String name, Object value);
+
+	/**
+	 * Sets extensions property of a RequestBody instance
+	 * to the parameter.
+	 *
+	 * @param extensions
+	 */
+
+	void setExtensions(Map<String, Object> extensions);
+
+	/**
+	 * returns the $ref property from a RequestBody instance.
+	 *
+	 * @return String $ref
+	 **/
+
+	String get$ref();
+
+	/**
+	 * Sets $ref property of a RequestBody instance
+	 * to the parameter.
+	 *
+	 * @param $ref
+	 */
+
+	void set$ref(String $ref);
+
+	/**
+	 * Sets $ref property of a RequestBody instance
+	 * to the parameter and return the instance.
+	 *
+	 * @param $ref
+	 * @return RequestBody instance with the set $ref property.
+	 */
+
+	RequestBody $ref(String $ref);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/package-info.java
new file mode 100644
index 000000000..c48690c11
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/package-info.java
@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.openapi.models.parameters;
\ No newline at end of file
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
new file mode 100644
index 000000000..817a967b4
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/ApiResponse.java
@@ -0,0 +1,214 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.responses;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.headers.Header;
+import org.eclipse.microprofile.openapi.models.links.Link;
+import org.eclipse.microprofile.openapi.models.media.Content;
+
+/**
+ * ApiResponse
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#responseObject"
+ */
+public interface ApiResponse extends Constructible {
+
+	/**
+	 * returns the description property from a ApiResponse instance.
+	 *
+	 * @return String description
+	 **/
+
+	String getDescription();
+
+	/**
+	 * Sets the description property of a ApiResponse instance
+	 * to the parameter.
+	 *
+	 * @param description
+	 */
+
+	void setDescription(String description);
+
+	/**
+	 * Sets the description property of a ApiResponse instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param description
+	 * @return ApiResponse instance with the set description property
+	 */
+
+	ApiResponse description(String description);
+
+	/**
+	 * returns the headers property from a ApiResponse instance.
+	 *
+	 * @return Map&lt;String, Header&gt; headers
+	 **/
+
+	Map<String, Header> getHeaders();
+
+	/**
+	 * Sets the headers property of a ApiResponse instance
+	 * to the parameter.
+	 *
+	 * @param headers
+	 */
+
+	void setHeaders(Map<String, Header> headers);
+
+	/**
+	 * Sets the headers property of a ApiResponse instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param headers
+	 * @return ApiResponse instance with the set headers property
+	 */
+
+	ApiResponse headers(Map<String, Header> headers);
+
+	/**
+	 * Adds a header item to the headers map of an ApiResponse instance
+	 * at the specified key and returns the instance.
+	 * If headers is null, creates a new HashMap and adds item to it.
+	 *
+	 * @param name - map key
+	 * @param header - map value
+	 * @return ApiResponse instance with the added header item
+	 */
+
+	ApiResponse addHeaderObject(String name, Header header);
+
+	/**
+	 * returns the content property from a ApiResponse instance.
+	 *
+	 * @return Content content
+	 **/
+
+	Content getContent();
+
+	/**
+	 * Sets the content property of an ApiResponse instance
+	 * to the parameter.
+	 *
+	 * @param content
+	 */
+
+	void setContent(Content content);
+
+	/**
+	 * Sets the content property of an ApiResponse instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param content
+	 * @return ApiResponse instance with the set content property
+	 */
+
+	ApiResponse content(Content content);
+
+	/**
+	 * returns the links property from a ApiResponse instance.
+	 *
+	 * @return Link links
+	 **/
+
+	Map<String, Link> getLinks();
+
+	/**
+	 * Sets the links property of an ApiResponse instance
+	 * to the parameter.
+	 *
+	 * @param links
+	 */
+
+	void setLinks(Map<String, Link> links);
+
+	/**
+	 * Sets the links property of an ApiResponse instance
+	 * using key, value pair and returns the instance.
+	 * <p>
+	 * If links is null, creates a new HashMap and adds the
+	 * key-value pair to it.
+	 *
+	 * @param link
+	 * @param link
+	 * @return ApiResponse instance with the set links property
+	 */
+
+	ApiResponse link(String name, Link link);
+
+	/**
+	 * returns the $ref property from an ApiResponse instance.
+	 *
+	 * @return String $ref
+	 **/
+	String get$ref();
+
+	/**
+	 * Sets the $ref property of an ApiResponse instance
+	 * to the parameter.
+	 *
+	 * @param String $ref
+	 */
+
+	void set$ref(String $ref);
+
+	/**
+	 * Sets the $ref property of an ApiResponse instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param $ref
+	 * @return ApiResponse instance with the set $ref property
+	 */
+
+	ApiResponse $ref(String $ref);
+
+	/**
+	 * Returns extensions property of a ApiResponse instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds an object item to extensions map at
+	 * the specified key.
+	 * <p>
+	 * If extensions is null, creates a new HashMap
+	 * and adds item to it
+	 *
+	 * @param name - map key
+	 * @param value - map value
+	 */
+
+	void addExtension(String name, Object value);
+
+	/**
+	 * Sets extensions property of a ApiResponse instance
+	 * to the parameter.
+	 *
+	 * @param extensions
+	 */
+
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
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
new file mode 100644
index 000000000..f45759f9c
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/ApiResponses.java
@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.responses;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * ApiResponses
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#responsesObject"
+ */
+public interface ApiResponses extends Constructible, Map<String, ApiResponse> {
+
+	public static final String DEFAULT = "default";
+
+	ApiResponses addApiResponse(String name, ApiResponse item);
+
+	/**
+	 * returns the default property from a ApiResponses instance.
+	 *
+	 * @return ApiResponse _default
+	 **/
+
+	ApiResponse getDefault();
+
+	/**
+	 * Sets _default property of an ApiResponses instance
+	 * to the parameter.
+	 *
+	 * @param _default
+	 */
+
+	void setDefault(ApiResponse _default);
+
+	/**
+	 * Sets _default property of an ApiResponses instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param _default
+	 * @return ApiResponses instance with the set _default property
+	 */
+
+	ApiResponses _default(ApiResponse _default);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/package-info.java
new file mode 100644
index 000000000..c73626f0b
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/package-info.java
@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.openapi.models.responses;
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java
new file mode 100644
index 000000000..39de69773
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java
@@ -0,0 +1,168 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.security;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * OAuthFlow
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#oauthFlowsObject"
+ */
+public interface OAuthFlow extends Constructible {
+
+	/**
+	 * returns the authorizationUrl property from a OAuthFlow instance.
+	 *
+	 * @return String authorizationUrl
+	 **/
+
+	String getAuthorizationUrl();
+
+	/**
+	 * Sets the authorizationUrl property of an OAuthFlow instance
+	 * to the parameter.
+	 *
+	 * @param authorizationUrl
+	 */
+
+	void setAuthorizationUrl(String authorizationUrl);
+
+	/**
+	 * Sets the authorizationUrl property of an OAuthFlow instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param authorizationUrl
+	 * @return OAuthFlow instance with the set authorizationUrl property
+	 */
+
+	OAuthFlow authorizationUrl(String authorizationUrl);
+
+	/**
+	 * returns the tokenUrl property from a OAuthFlow instance.
+	 *
+	 * @return String tokenUrl
+	 **/
+
+	String getTokenUrl();
+
+	/**
+	 * Sets the tokenUrl property of an OAuthFlow instance.
+	 *
+	 * @param tokenkUrl
+	 */
+
+	void setTokenUrl(String tokenUrl);
+
+	/**
+	 * Sets the tokenUrl property of an OAuthFlow instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param tokenUrl
+	 * @return OAuthFlow instance with the set tokenUrl property
+	 */
+
+	OAuthFlow tokenUrl(String tokenUrl);
+
+	/**
+	 * returns the refreshUrl property from a OAuthFlow instance.
+	 *
+	 * @return String refreshUrl
+	 **/
+
+	String getRefreshUrl();
+
+	/**
+	 * Sets the refreshUrl property of an OAuthFlow instance
+	 * to the parameter.
+	 *
+	 * @param refreshUrl
+	 */
+
+	void setRefreshUrl(String refreshUrl);
+
+	/**
+	 * Sets the refreshUrl property of an OAuthFlow instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param refreshUrl
+	 * @return OAuthFlow instance with the set refreshUrl property
+	 */
+
+	OAuthFlow refreshUrl(String refreshUrl);
+
+	/**
+	 * returns the scopes property from a OAuthFlow instance.
+	 *
+	 * @return Scopes scopes
+	 **/
+
+	Scopes getScopes();
+
+	/**
+	 * Sets the scopes property of an OAuthFlow instance
+	 * to the parameter.
+	 *
+	 * @param scopes
+	 */
+
+	void setScopes(Scopes scopes);
+
+	/**
+	 * Sets the scopes property of an OAuthFlow instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param scopes
+	 * @return OAuthFlow instance with the set scopes property
+	 */
+
+	OAuthFlow scopes(Scopes scopes);
+
+	/**
+	 * Returns extensions property of a OAuthFlow instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds an object item to extensions map at
+	 * the specified key.
+	 * <p>
+	 * If extensions is null, creates a new HashMap
+	 * and adds item to it
+	 *
+	 * @param name - map key
+	 * @param value - map value
+	 */
+
+	void addExtension(String name, Object value);
+
+	/**
+	 * Sets extensions property of a OAuthFlow instance
+	 * to the parameter.
+	 *
+	 * @param extensions
+	 */
+
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java
new file mode 100644
index 000000000..ddd00742a
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java
@@ -0,0 +1,167 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.security;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * OAuthFlows
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#oauthFlowsObject"
+ */
+public interface OAuthFlows extends Constructible {
+
+	/**
+	 * returns the implicit property from a OAuthFlows instance.
+	 *
+	 * @return OAuthFlow implicit
+	 **/
+
+	OAuthFlow getImplicit();
+
+	/**
+	 * Sets the implicit property of an OAuthFlows instance
+	 * to parameter.
+	 *
+	 * @param implicit
+	 */
+
+	void setImplicit(OAuthFlow implicit);
+
+	/**
+	 * Sets the implicit property of an OAuthFlows instance
+	 * to parameter and returns the instance.
+	 *
+	 * @param implicit
+	 * @return OAuthFlows instance with the set implicit property
+	 */
+
+	OAuthFlows implicit(OAuthFlow implicit);
+
+	/**
+	 * returns the password property from a OAuthFlows instance.
+	 *
+	 * @return OAuthFlow password
+	 **/
+
+	OAuthFlow getPassword();
+
+	/**
+	 * Sets the password property of an OAuthFlows instance
+	 * to parameter.
+	 *
+	 * @param password
+	 */
+
+	void setPassword(OAuthFlow password);
+
+	/**
+	 * Sets the password property of an OAuthFlows instance
+	 * to parameter and returns the instance.
+	 *
+	 * @param password
+	 * @return OAuthFlows instance with the set password property
+	 */
+
+	OAuthFlows password(OAuthFlow password);
+
+	/**
+	 * returns the clientCredentials property from a OAuthFlows instance.
+	 *
+	 * @return OAuthFlow clientCredentials
+	 **/
+
+	OAuthFlow getClientCredentials();
+
+	/**
+	 * Sets the clientCredentials property of an OAuthFlows instance
+	 * to parameter.
+	 *
+	 * @param clientCredentials
+	 */
+
+	void setClientCredentials(OAuthFlow clientCredentials);
+
+	/**
+	 * Sets the clientCredentials property of an OAuthFlows instance
+	 * to parameter and returns the instance.
+	 *
+	 * @param clientCredentials
+	 * @return OAuthFlows instance with the set clientCredentials property
+	 */
+
+	OAuthFlows clientCredentials(OAuthFlow clientCredentials);
+
+	/**
+	 * returns the authorizationCode property from a OAuthFlows instance.
+	 *
+	 * @return OAuthFlow authorizationCode
+	 **/
+
+	OAuthFlow getAuthorizationCode();
+
+	/**
+	 * Sets the authorizationCode property of an OAuthFlows instance
+	 * to parameter.
+	 *
+	 * @param authorizationCode
+	 */
+
+	void setAuthorizationCode(OAuthFlow authorizationCode);
+
+	/**
+	 * Sets the authorizationCode property of an OAuthFlows instance
+	 * to parameter and returns the instance.
+	 *
+	 * @param authorizationCode
+	 * @return OAuthFlows instance with the set authorizationCode property
+	 */
+
+	OAuthFlows authorizationCode(OAuthFlow authorizationCode);
+
+	/**
+	 * Returns extensions property of an OAuthFlows instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds an object item to extensions map of an OAuthFlows instance
+	 * at the specified key.
+	 * If extensions is null, then creates a new HashMap and adds the item.
+	 *
+	 * @param name
+	 * @param value
+	 */
+
+	void addExtension(String name, Object value);
+
+	/**
+	 * Sets extensions property of an OAuthFlows instance
+	 * to the parameter.
+	 *
+	 * @param extensions
+	 */
+
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
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
new file mode 100644
index 000000000..8499b94a5
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/Scopes.java
@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.security;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * Scopes
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#scopedObject"
+ */
+public interface Scopes extends Constructible, Map<String, String> {
+
+	/**
+	 * Adds name and item parameters to a Scopes instance
+	 * as a key-value
+	 *
+	 * @param name
+	 * @param item
+	 * @return Scopes instance with the added key-value pair
+	 */
+
+	Scopes addString(String name, String item);
+
+	/**
+	 * Returns extensions property of an Scopes instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds an object item to extensions map of an Scopes instance
+	 * at the specified key.
+	 * If extensions is null, then creates a new HashMap and adds the item.
+	 *
+	 * @param name
+	 * @param value
+	 */
+
+	void addExtension(String name, Object value);
+
+	/**
+	 * Sets extensions property of an Scopes instance
+	 * to the parameter.
+	 *
+	 * @param extensions
+	 */
+
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
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
new file mode 100644
index 000000000..b67689189
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityRequirement.java
@@ -0,0 +1,69 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.security;
+
+import java.util.List;
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * SecurityRequirement
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#securityRequirementObject"
+ */
+public interface SecurityRequirement extends Constructible, Map<String, List<String>> {
+
+	/**
+	 * Adds a List item to a SecurityRequirement instance
+	 * based on the name and item parameters provided as key-value pair.
+	 * <p>
+	 * Takes value as a String.
+	 * 
+	 * @param name
+	 * @param item
+	 * @return Updated SecurityRequirements instance
+	 */
+
+	SecurityRequirement addList(String name, String item);
+
+	/**
+	 * Adds a List item to a SecurityRequirement instance
+	 * based on the name and item parameters provided as key-value pair
+	 * to the map.
+	 * <p>
+	 * Takes value as a List of strings.
+	 * 
+	 * @param name
+	 * @param item
+	 * @return Updated SecurityRequirements instance
+	 */
+
+	SecurityRequirement addList(String name, List<String> item);
+
+	/**
+	 * Adds a new empty List item to a SecurityRequirement instance
+	 * based on the name parameter provided as key to the map.
+	 * 
+	 * @param name
+	 * @return Updated SecurityRequirements instance
+	 */
+
+	SecurityRequirement addList(String name);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java
new file mode 100644
index 000000000..f4aabc8c5
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java
@@ -0,0 +1,342 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.security;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * SecurityScheme
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#securitySchemeObject"
+ */
+public interface SecurityScheme extends Constructible {
+
+	/**
+	 * Gets or Sets type
+	 */
+	public enum Type {
+	    APIKEY("apiKey"),
+	    HTTP("http"),
+	    OAUTH2("oauth2"),
+	    OPENIDCONNECT("openIdConnect");
+	
+	    private final String value;
+	
+	    Type(String value) {
+	        this.value = value;
+	    }
+	
+	    @Override
+	    public String toString() {
+	        return String.valueOf(value);
+	    }
+	}
+
+	/**
+	 * Gets or Sets in
+	 */
+	public enum In {
+	    COOKIE("cookie"),
+	    HEADER("header"),
+	    QUERY("query");
+	
+	    private final String value;
+	
+	    In(String value) {
+	        this.value = value;
+	    }
+	
+	    @Override
+	    public String toString() {
+	        return String.valueOf(value);
+	    }
+	}
+
+	/**
+	 * returns the type property from a SecurityScheme instance.
+	 *
+	 * @return Type type
+	 **/
+
+	SecurityScheme.Type getType();
+
+	/**
+	 * Sets the type property of a SecurityScheme instance
+	 * to the parameter
+	 *
+	 * @param type
+	 */
+
+	void setType(SecurityScheme.Type type);
+
+	/**
+	 * Sets the type property of a SecurityScheme instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param type
+	 * @return SecurityScheme instance with the set type property
+	 */
+
+	SecurityScheme type(SecurityScheme.Type type);
+
+	/**
+	 * returns the description property from a SecurityScheme instance.
+	 *
+	 * @return String description
+	 **/
+
+	String getDescription();
+
+	/**
+	 * Sets the description property of a SecurityScheme instance
+	 * to the parameter.
+	 *
+	 * @param description
+	 */
+
+	void setDescription(String description);
+
+	/**
+	 * Sets the description property of a SecurityScheme instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param description
+	 * @return SecurityScheme instance with the set description property
+	 */
+
+	SecurityScheme description(String description);
+
+	/**
+	 * returns the name property from a SecurityScheme instance.
+	 *
+	 * @return String name
+	 **/
+
+	String getName();
+
+	/**
+	 * Sets the name property of a SecurityScheme instance
+	 * to the parameter.
+	 *
+	 * @param name
+	 */
+
+	void setName(String name);
+
+	/**
+	 * Sets the name property of a SecurityScheme instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param name
+	 * @return SecurityScheme instance with the set name property
+	 */
+
+	SecurityScheme name(String name);
+
+	/**
+	 * returns the in property from a SecurityScheme instance.
+	 *
+	 * @return In in
+	 **/
+
+	SecurityScheme.In getIn();
+
+	/**
+	 * Sets the in property of a SecurityScheme instance
+	 * to the parameter.
+	 *
+	 * @param in
+	 */
+
+	void setIn(SecurityScheme.In in);
+
+	/**
+	 * Sets the in property of a SecurityScheme instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param in
+	 * @return SecurityScheme instance with the set in property
+	 */
+
+	SecurityScheme in(SecurityScheme.In in);
+
+	/**
+	 * returns the scheme property from a SecurityScheme instance.
+	 *
+	 * @return String scheme
+	 **/
+
+	String getScheme();
+
+	/**
+	 * Sets the scheme property of a SecurityScheme instance
+	 * to the parameter.
+	 *
+	 * @param scheme
+	 */
+
+	void setScheme(String scheme);
+
+	/**
+	 * Sets the scheme property of a SecurityScheme instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param scheme
+	 * @return SecurityScheme instance with the set scheme property
+	 */
+
+	SecurityScheme scheme(String scheme);
+
+	/**
+	 * returns the bearerFormat property from a SecurityScheme instance.
+	 *
+	 * @return String bearerFormat
+	 **/
+
+	String getBearerFormat();
+
+	/**
+	 * Sets the bearerFormat property of a SecurityScheme instance
+	 * to the parameter.
+	 *
+	 * @param bearerFormat
+	 */
+
+	void setBearerFormat(String bearerFormat);
+
+	/**
+	 * Sets the bearerFormat property of a SecurityScheme instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param bearerFormat
+	 * @return SecurityScheme instance with the set bearerFormat property
+	 */
+
+	SecurityScheme bearerFormat(String bearerFormat);
+
+	/**
+	 * returns the flows property from a SecurityScheme instance.
+	 *
+	 * @return OAuthFlows flows
+	 **/
+
+	OAuthFlows getFlows();
+
+	/**
+	 * Sets the flows property of a SecurityScheme instance
+	 * to the parameter.
+	 *
+	 * @param flows
+	 */
+
+	void setFlows(OAuthFlows flows);
+
+	/**
+	 * Sets the flows property of a SecurityScheme instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param flows
+	 * @return SecurityScheme instance with the set flows property
+	 */
+
+	SecurityScheme flows(OAuthFlows flows);
+
+	/**
+	 * returns the openIdConnectUrl property from a SecurityScheme instance.
+	 *
+	 * @return String openIdConnectUrl
+	 **/
+
+	String getOpenIdConnectUrl();
+
+	/**
+	 * Sets the openIdConnectUrl property of a SecurityScheme instance
+	 * to the parameter.
+	 *
+	 * @param openIdConnectUrl
+	 */
+
+	void setOpenIdConnectUrl(String openIdConnectUrl);
+
+	/**
+	 * Sets the openIdConnectUrl property of a SecurityScheme instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param openIdConnectUrl
+	 * @return SecurityScheme instance with the set openIdConnectUrl property
+	 */
+
+	SecurityScheme openIdConnectUrl(String openIdConnectUrl);
+
+	/**
+	 * Returns extensions property of a SecurityScheme instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds an object item to extensions map of a SecurityScheme instance
+	 * at the specified key.
+	 * If extensions is null, then creates a new HashMap and adds the item.
+	 *
+	 * @param name
+	 * @param value
+	 */
+
+	void addExtension(String name, Object value);
+
+	/**
+	 * Sets extensions property of a SecurityScheme instance
+	 * to the parameter.
+	 *
+	 * @param extensions
+	 */
+
+	void setExtensions(Map<String, Object> extensions);
+
+	/**
+	 * returns the $ref property from an SecurityScheme instance.
+	 *
+	 * @return String $ref
+	 **/
+	String get$ref();
+
+	/**
+	 * Sets the $ref property of a SecurityScheme instance
+	 * to the parameter.
+	 *
+	 * @param $ref
+	 */
+
+	void set$ref(String $ref);
+
+	/**
+	 * Sets the $ref property of a SecurityScheme instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param $ref
+	 * @return SecurityScheme instance with the set $ref property
+	 */
+
+	SecurityScheme $ref(String $ref);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/package-info.java
new file mode 100644
index 000000000..5a4458dff
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/package-info.java
@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.openapi.models.security;
\ No newline at end of file
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
new file mode 100644
index 000000000..670e64f2f
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/Server.java
@@ -0,0 +1,140 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.servers;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * Server
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#serverObject"
+ */
+public interface Server extends Constructible  {
+
+	/**
+	 * returns the url property from a Server instance.
+	 *
+	 * @return String url
+	 **/
+
+	String getUrl();
+
+	/**
+	 * Sets the url property of a Server instance
+	 * to the parameter.
+	 * 
+	 * @param url
+	 */
+
+	void setUrl(String url);
+
+	/**
+	 * Sets the url property of a Server instance
+	 * to the parameter and returns the instance.
+	 * 
+	 * @param url
+	 * @return Server instance with the set url property.
+	 */
+
+	Server url(String url);
+
+	/**
+	 * returns the description property from a Server instance.
+	 *
+	 * @return String description
+	 **/
+
+	String getDescription();
+
+	/**
+	 * Sets the description property of a Server instance
+	 * to the parameter.
+	 * 
+	 * @param description
+	 */
+
+	void setDescription(String description);
+
+	/**
+	 * Sets the description property of a Server instance
+	 * to the parameter and returns the instance.
+	 * 
+	 * @param description
+	 * @return Server instance with the set description property.
+	 */
+
+	Server description(String description);
+
+	/**
+	 * returns the variables property from a Server instance.
+	 *
+	 * @return ServerVariables variables
+	 **/
+
+	ServerVariables getVariables();
+
+	/**
+	 * Sets the variables property of a Server instance
+	 * to the parameter.
+	 * 
+	 * @param variables
+	 */
+
+	void setVariables(ServerVariables variables);
+
+	/**
+	 * Sets the variables property of a Server instance
+	 * to the parameter and returns the instance.
+	 * 
+	 * @param variables
+	 * @return Server instance with the set variables property.
+	 */
+
+	Server variables(ServerVariables variables);
+
+	/**
+	 * Returns extensions property of a Server instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds an object item to extensions map of a Server instance
+	 * at the specified key.
+	 * If extensions is null, then creates a new HashMap and adds the item.
+	 *
+	 * @param name
+	 * @param value
+	 */
+
+	void addExtension(String name, Object value);
+
+	/**
+	 * Sets extensions property of a Server instance
+	 * to the parameter.
+	 *
+	 * @param extensions
+	 */
+
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java
new file mode 100644
index 000000000..1320dbc2c
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java
@@ -0,0 +1,153 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.servers;
+
+import java.util.List;
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * ServerVariable
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#serverVariableObject"
+ */
+public interface ServerVariable extends Constructible {
+
+	/**
+	 * returns the _enum property from a ServerVariable instance.
+	 *
+	 * @return List&lt;String&gt; _enum
+	 **/
+
+	List<String> getEnum();
+
+	/**
+	 * Sets the _enum property of a ServerVariable instance
+	 * to parameter.
+	 * 
+	 * @param _enum
+	 */
+
+	void setEnum(List<String> _enum);
+
+	/**
+	 * Sets the _enum property of a ServerVariable instance
+	 * to parameter and returns the instance.
+	 * 
+	 * @param _enum
+	 * @return ServerVariable instance with the set _enum property
+	 */
+
+	ServerVariable _enum(List<String> _enum);
+
+	/**
+	 * Adds a string item to _enum list of a ServerVariable instance
+	 * and returns the instance.
+	 * <p>
+	 * If the _enum list is null, creates a new ArrayList and adds the item.
+	 * 
+	 * @param _enumItem
+	 * @return ServerVariable instance with the added enum item.
+	 */
+
+	ServerVariable addEnumItem(String _enumItem);
+
+	/**
+	 * returns the _default property from a ServerVariable instance.
+	 *
+	 * @return String _default
+	 **/
+
+	String getDefault();
+
+	/**
+	 * Sets the _default property of a ServerVariable instance
+	 * to parameter.
+	 * 
+	 * @param _default
+	 */
+
+	void setDefault(String _default);
+
+	/**
+	 * Sets the _default property of a ServerVariable instance
+	 * to parameter and returns the instance.
+	 * 
+	 * @param _default
+	 * @return ServerVariable instance with the set _default property
+	 */
+
+	ServerVariable _default(String _default);
+
+	/**
+	 * returns the description property from a ServerVariable instance.
+	 *
+	 * @return String description
+	 **/
+
+	String getDescription();
+
+	/**
+	 * Sets the description property of a ServerVariable instance
+	 * to parameter.
+	 * 
+	 * @param description
+	 */
+
+	void setDescription(String description);
+
+	/**
+	 * Sets the description property of a ServerVariable instance
+	 * to parameter and returns the instance.
+	 * 
+	 * @param description
+	 * @return ServerVariable instance with the set description property
+	 */
+
+	ServerVariable description(String description);
+
+	/**
+	 * Returns extensions property of a ServerVariable instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds an object item to extensions map of a ServerVariable instance
+	 * at the specified key.
+	 * If extensions is null, then creates a new HashMap and adds the item.
+	 *
+	 * @param name
+	 * @param value
+	 */
+
+	void addExtension(String name, Object value);
+
+	/**
+	 * Sets extensions property of a ServerVariable instance
+	 * to the parameter.
+	 *
+	 * @param extensions
+	 */
+
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ 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
new file mode 100644
index 000000000..65775e710
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariables.java
@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.servers;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+/**
+ * ServerVariables
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#serverVariablesObject"
+ */
+public interface ServerVariables extends Constructible, Map<String, ServerVariable> {
+
+	/**
+	 * Adds a key-value item to a ServerVariables instance from
+	 * the name-item parameter pair and returns the modified instance.
+	 *
+	 * @param name
+	 * @param item
+	 * @return ServerVariables instance with the added name-item pair.
+	 */
+
+	ServerVariables addServerVariable(String name, ServerVariable item);
+
+	Map<String, Object> getExtensions();
+
+	void addExtension(String name, Object value);
+
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/package-info.java
new file mode 100644
index 000000000..03bf591b7
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/package-info.java
@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.openapi.models.servers;
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
new file mode 100644
index 000000000..43b49968e
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
@@ -0,0 +1,141 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.tags;
+
+import java.util.Map;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.ExternalDocumentation;
+
+/**
+ * Tag
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#tagObject"
+ */
+public interface Tag extends Constructible {
+
+	/**
+	 * returns the name property from a Tag instance.
+	 *
+	 * @return String name
+	 **/
+
+	String getName();
+
+	/**
+	 * Sets the name property of a Tag instance to the
+	 * parameter.
+	 * 
+	 * @param name
+	 */
+
+	void setName(String name);
+
+	/**
+	 * Sets the name property of a Tag instance to the
+	 * parameter and returns the instance.
+	 * 
+	 * @param name
+	 * @return Tag instance with the set name property
+	 */
+
+	Tag name(String name);
+
+	/**
+	 * returns the description property from a Tag instance.
+	 *
+	 * @return String description
+	 **/
+
+	String getDescription();
+
+	/**
+	 * Sets the description property of a Tag instance to the
+	 * parameter.
+	 * 
+	 * @param description
+	 */
+
+	void setDescription(String description);
+
+	/**
+	 * Sets the description property of a Tag instance to the
+	 * parameter and returns the instance.
+	 * 
+	 * @param description
+	 * @return Tag instance with the set description property
+	 */
+
+	Tag description(String description);
+
+	/**
+	 * returns the externalDocs property from a Tag instance.
+	 *
+	 * @return ExternalDocumentation externalDocs
+	 **/
+
+	ExternalDocumentation getExternalDocs();
+
+	/**
+	 * Sets the externalDocs property of a Tag instance to the
+	 * parameter.
+	 * 
+	 * @param externalDocs
+	 */
+
+	void setExternalDocs(ExternalDocumentation externalDocs);
+
+	/**
+	 * Sets the externalDocs property of a Tag instance to the
+	 * parameter and returns the instance.
+	 * 
+	 * @param externalDocs
+	 * @return Tag instance with the set externalDocs property
+	 */
+
+	Tag externalDocs(ExternalDocumentation externalDocs);
+
+	/**
+	 * Returns extensions property of a Tag instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 */
+
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds an object item to extensions map of a Tag instance
+	 * at the specified key.
+	 * If extensions is null, then creates a new HashMap and adds the item.
+	 *
+	 * @param name
+	 * @param value
+	 */
+
+	void addExtension(String name, Object value);
+
+	/**
+	 * Sets extensions property of a Tag instance
+	 * to the parameter.
+	 *
+	 * @param extensions
+	 */
+
+	void setExtensions(Map<String, Object> extensions);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/package-info.java
new file mode 100644
index 000000000..2c2898941
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/package-info.java
@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.openapi.models.tags;
\ No newline at end of file

From 36d5d3fd40c2d512ccee3ca9313538f3e93ab9d6 Mon Sep 17 00:00:00 2001
From: Michael Glavassevich <mrglavas@ca.ibm.com>
Date: Thu, 12 Oct 2017 14:38:01 -0400
Subject: [PATCH 02/23] Fixing some imports / references to java.util.Map.

Signed-off-by: Michael Glavassevich <mrglavas@ca.ibm.com>
---
 .../microprofile/openapi/models/examples/Example.java       | 6 ++++--
 .../eclipse/microprofile/openapi/models/headers/Header.java | 4 ++--
 .../microprofile/openapi/models/media/MediaType.java        | 4 ++--
 3 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
index 59d9777c6..61f4a880d 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
@@ -17,6 +17,8 @@
 
 package org.eclipse.microprofile.openapi.models.examples;
 
+import java.util.Map;
+
 import org.eclipse.microprofile.openapi.models.Constructible;
 
 /**
@@ -148,7 +150,7 @@ public interface Example extends Constructible {
 	 *
 	 * @return Map&lt;String, Object&gt; extensions
 	 **/
-	java.util.Map<String, Object> getExtensions();
+	Map<String, Object> getExtensions();
 
 	/**
 	 * Adds the given Object to this Example's map of extensions, with the given key as its key.
@@ -163,6 +165,6 @@ public interface Example extends Constructible {
 	 *
 	 * @return Map&lt;String, Object&gt; extensions
 	 **/
-	void setExtensions(java.util.Map<String, Object> extensions);
+	void setExtensions(Map<String, Object> extensions);
 
 }
\ No newline at end of file
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 9153f3d7c..cf6e5ee01 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
@@ -302,7 +302,7 @@ public String toString() {
 	 *
 	 * @return Map&lt;String, Object&gt; extensions
 	 */
-	java.util.Map<String, Object> getExtensions();
+	Map<String, Object> getExtensions();
 
 	/**
 	 * Adds the given Object to this Header's map of extensions, with the given key as its key.
@@ -317,7 +317,7 @@ public String toString() {
 	 *
 	 * @return Map&lt;String, Object&gt; extensions
 	 */
-	void setExtensions(java.util.Map<String, Object> extensions);
+	void setExtensions(Map<String, Object> extensions);
 
 	/**
 	 * returns the $ref property from a Header instance.
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 fae5aca84..9fff6d233 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
@@ -171,7 +171,7 @@ public interface MediaType extends Constructible {
 	 * @return Map&lt;String, Object&gt; extensions
 	 */
 
-	java.util.Map<String, Object> getExtensions();
+	Map<String, Object> getExtensions();
 
 	/**
 	 * Adds an object item to extensions map for
@@ -193,6 +193,6 @@ public interface MediaType extends Constructible {
 	 * @param extensions
 	 */
 
-	void setExtensions(java.util.Map<String, Object> extensions);
+	void setExtensions(Map<String, Object> extensions);
 
 }
\ No newline at end of file

From ecadeeb0d3702735d49266054991d49e6c5c694a Mon Sep 17 00:00:00 2001
From: Michael Glavassevich <mrglavas@ca.ibm.com>
Date: Mon, 16 Oct 2017 14:53:18 -0400
Subject: [PATCH 03/23] Adding sub-interfaces for Schema.

Signed-off-by: Michael Glavassevich <mrglavas@ca.ibm.com>
---
 .../openapi/models/media/ArraySchema.java     |  49 +++++++
 .../openapi/models/media/BinarySchema.java    |  68 ++++++++++
 .../openapi/models/media/BooleanSchema.java   |  59 +++++++++
 .../openapi/models/media/ByteArraySchema.java |  68 ++++++++++
 .../openapi/models/media/ComposedSchema.java  | 123 ++++++++++++++++++
 .../openapi/models/media/DateSchema.java      |  69 ++++++++++
 .../openapi/models/media/EmailSchema.java     |  68 ++++++++++
 .../openapi/models/media/FileSchema.java      |  45 +++++++
 .../openapi/models/media/IntegerSchema.java   |  84 ++++++++++++
 .../openapi/models/media/MapSchema.java       |  35 +++++
 .../openapi/models/media/NumberSchema.java    |  73 +++++++++++
 .../openapi/models/media/ObjectSchema.java    |  35 +++++
 .../openapi/models/media/PasswordSchema.java  |  80 ++++++++++++
 .../openapi/models/media/StringSchema.java    |  76 +++++++++++
 .../openapi/models/media/UUIDSchema.java      | 101 ++++++++++++++
 15 files changed, 1033 insertions(+)
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/ArraySchema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/BinarySchema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/BooleanSchema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/ByteArraySchema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/ComposedSchema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/DateSchema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/EmailSchema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/FileSchema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/IntegerSchema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/MapSchema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/NumberSchema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/ObjectSchema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/PasswordSchema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/StringSchema.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/media/UUIDSchema.java

diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ArraySchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ArraySchema.java
new file mode 100644
index 000000000..8c0dd5737
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ArraySchema.java
@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+/**
+ * ArraySchema
+ */
+public interface ArraySchema extends Schema {
+
+	/**
+	   * returns the items property from a ArraySchema instance.
+	   *
+	   * @return Schema items
+	   **/
+
+	Schema getItems();
+
+	/**
+	   * sets this ArraySchema's items property to the given items.
+	   *
+	   * @param SchemaImpl items
+	   */
+	void setItems(Schema items);
+
+	/**
+	   * sets this ArraySchema's items property to the given items and
+	   * returns this instance of ArraySchema
+	   *
+	   * @param SchemaImpl items
+	   * @return ArraySchema
+	   */
+	ArraySchema items(Schema items);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/BinarySchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/BinarySchema.java
new file mode 100644
index 000000000..4ca083a08
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/BinarySchema.java
@@ -0,0 +1,68 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.List;
+
+/**
+ * BinarySchema
+ */
+public interface BinarySchema extends Schema<byte[]> {
+
+	/**
+	   * sets this BinarySchema's type property to the given type and
+	   * returns this instance of BinarySchema
+	   *
+	   * @param String type
+	   * @return BinarySchema
+	   */
+	BinarySchema type(String type);
+
+	/**
+	   * sets this BinarySchema's format property to the given format and
+	   * returns this instance of BinarySchema
+	   *
+	   * @param String format
+	   * @return BinarySchema
+	   */
+	BinarySchema format(String format);
+
+	/**
+	   * sets the _default property of this BinarySchema to the given _default value.
+	   * 
+	   * @param byte[] _default
+	   * @return BinarySchema
+	   */
+	BinarySchema _default(byte[] _default);
+
+	/**
+	   * sets the _enum property of this BinarySchema to the given _enum value.
+	   * 
+	   * @param List&lt;byte[]&gt; _enum
+	   * @return BinarySchema
+	   */
+	BinarySchema _enum(List<byte[]> _enum);
+
+	/**
+	   * Adds the given _enumItem to this BinarySchema's List of _enumItems.
+	   *
+	   * @param byte[] _enumItem
+	   */
+	BinarySchema addEnumItem(byte[] _enumItem);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/BooleanSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/BooleanSchema.java
new file mode 100644
index 000000000..147137fe8
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/BooleanSchema.java
@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.List;
+
+/**
+ * BooleanSchema
+ */
+public interface BooleanSchema extends Schema<Boolean> {
+
+	/**
+	   * sets this BooleanSchema's type property to the given type and
+	   * returns this instance of BooleanSchema
+	   *
+	   * @param String type
+	   * @return BooleanSchema
+	   */
+	BooleanSchema type(String type);
+
+	/**
+	   * sets the _default property of this BooleanSchema to the given _default value.
+	   * 
+	   * @param byte[] _default
+	   * @return BooleanSchema
+	   */
+	BooleanSchema _default(Boolean _default);
+
+	/**
+	   * sets the _enum property of this BooleanSchema to the given _enum value.
+	   * 
+	   * @param List&lt;byte[]&gt; _enum
+	   * @return BooleanSchema
+	   */
+	BooleanSchema _enum(List<Boolean> _enum);
+
+	/**
+	   * Adds the given _enumItem to this BooleanSchema's List of _enumItems.
+	   *
+	   * @param byte[] _enumItem
+	   */
+	BooleanSchema addEnumItem(Boolean _enumItem);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ByteArraySchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ByteArraySchema.java
new file mode 100644
index 000000000..d2f6ff6f1
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ByteArraySchema.java
@@ -0,0 +1,68 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.List;
+
+/**
+ * ByteArraySchema
+ */
+public interface ByteArraySchema extends Schema<byte[]> {
+
+	/**
+	   * sets this ByteArraySchema's type property to the given type and
+	   * returns this instance of ByteArraySchema
+	   *
+	   * @param String type
+	   * @return ByteArraySchema
+	   */
+	ByteArraySchema type(String type);
+
+	/**
+	   * sets this ByteArraySchema's format property to the given format and
+	   * returns this instance of ByteArraySchema
+	   *
+	   * @param String format
+	   * @return ByteArraySchema
+	   */
+	ByteArraySchema format(String format);
+
+	/**
+	   * sets the _default property of this ByteArraySchema to the given _default value.
+	   * 
+	   * @param byte[] _default
+	   * @return ByteArraySchema
+	   */
+	ByteArraySchema _default(byte[] _default);
+
+	/**
+	   * sets the _enum property of this ByteArraySchema to the given _enum value.
+	   * 
+	   * @param List&lt;byte[]&gt; _enum
+	   * @return ByteArraySchema
+	   */
+	ByteArraySchema _enum(List<byte[]> _enum);
+
+	/**
+	   * Adds the given _enumItem to this ByteArraySchema's List of _enumItems.
+	   *
+	   * @param byte[] _enumItem
+	   */
+	ByteArraySchema addEnumItem(byte[] _enumItem);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ComposedSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ComposedSchema.java
new file mode 100644
index 000000000..d00427161
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ComposedSchema.java
@@ -0,0 +1,123 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.List;
+
+/**
+ * ComposedSchema
+ */
+public interface ComposedSchema extends Schema {
+
+	/**
+	   * returns the allOf property from a ComposedSchema instance.
+	   *
+	   * @return List&lt;Schema&gt; allOf
+	   **/
+
+	List<Schema> getAllOf();
+
+	/**
+	   * sets the allOf property of this instance of ComposedSchema
+	   * 
+	   * @param List&lt;Schema&gt; allOf
+	   */
+	void setAllOf(List<Schema> allOf);
+
+	/**
+	   * sets the allOf property of this instance of ComposedSchema 
+	   * and returns this ComposedSchema
+	   * 
+	   * @param List&lt;Schema&gt; allOf
+	   * @return ComposedSchema
+	   */
+	ComposedSchema allOf(List<Schema> allOf);
+
+	/**
+	    * adds the given allOfItem Schema to this ComposedSchema's list of allOfItems
+	    * 
+	    * @param Schema allOfItem
+	    * @return ComposedSchema
+	    */
+	ComposedSchema addAllOfItem(Schema allOfItem);
+
+	/**
+	   * returns the anyOf property from a ComposedSchema instance.
+	   *
+	   * @return List&lt;Schema&gt; anyOf
+	   **/
+
+	List<Schema> getAnyOf();
+
+	/**
+	   * sets the anyOf property of this instance of ComposedSchema
+	   * 
+	   * @param List&lt;Schema&gt; anyOf
+	   */
+	void setAnyOf(List<Schema> anyOf);
+
+	/**
+	   * sets the anyOf property of this instance of ComposedSchema 
+	   * and returns this ComposedSchema
+	   * 
+	   * @param List&lt;Schema&gt; anyOf
+	   * @return ComposedSchema
+	   */
+	ComposedSchema anyOf(List<Schema> anyOf);
+
+	/**
+	    * adds the given anyOfItem Schema to this ComposedSchema's list of anyOfItems
+	    * 
+	    * @param Schema anyOfItem
+	    * @return ComposedSchema
+	    */
+	ComposedSchema addAnyOfItem(Schema anyOfItem);
+
+	/**
+	   * returns the oneOf property from a ComposedSchema instance.
+	   *
+	   * @return List&lt;Schema&gt; oneOf
+	   **/
+
+	List<Schema> getOneOf();
+
+	/**
+	   * sets the oneOf property of this instance of ComposedSchema
+	   * 
+	   * @param List&lt;Schema&gt; oneOf
+	   */
+	void setOneOf(List<Schema> oneOf);
+
+	/**
+	   * sets the oneOf property of this instance of ComposedSchema 
+	   * and returns this ComposedSchema
+	   * 
+	   * @param List&lt;Schema&gt; oneOf
+	   * @return ComposedSchema
+	   */
+	ComposedSchema oneOf(List<Schema> oneOf);
+
+	/**
+	    * adds the given oneOfItem Schema to this ComposedSchema's list of oneOfItems
+	    * 
+	    * @param Schema oneOfItem
+	    * @return ComposedSchema
+	    */
+	ComposedSchema addOneOfItem(Schema oneOfItem);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/DateSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/DateSchema.java
new file mode 100644
index 000000000..4b4f4f7f5
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/DateSchema.java
@@ -0,0 +1,69 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.Date;
+import java.util.List;
+
+/**
+ * DateSchema
+ */
+public interface DateSchema extends Schema<Date> {
+
+	/**
+	   * sets this DateSchema's type property to the given type and
+	   * returns this instance of DateSchema
+	   *
+	   * @param String type
+	   * @return DateSchema
+	   */
+	DateSchema type(String type);
+
+	/**
+	   * sets this DateSchema's format property to the given format and
+	   * returns this instance of DateSchema
+	   *
+	   * @param String format
+	   * @return DateSchema
+	   */
+	DateSchema format(String format);
+
+	/**
+	   * sets the _default property of this DateSchema to the given _default value.
+	   * 
+	   * @param byte[] _default
+	   * @return DateSchema
+	   */
+	DateSchema _default(Date _default);
+
+	/**
+	   * sets the _enum property of this DateSchema to the given _enum value.
+	   * 
+	   * @param List&lt;byte[]&gt; _enum
+	   * @return DateSchema
+	   */
+	DateSchema _enum(List<Date> _enum);
+
+	/**
+	   * Adds the given _enumItem to this DateSchema's List of _enumItems.
+	   *
+	   * @param byte[] _enumItem
+	   */
+	DateSchema addEnumItem(Date _enumItem);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/EmailSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/EmailSchema.java
new file mode 100644
index 000000000..13e5b478b
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/EmailSchema.java
@@ -0,0 +1,68 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.List;
+
+/**
+ * EmailSchema
+ */
+public interface EmailSchema extends Schema<String> {
+
+	/**
+	   * sets this EmailSchema's type property to the given type and
+	   * returns this instance of EmailSchema
+	   *
+	   * @param String type
+	   * @return EmailSchema
+	   */
+	EmailSchema type(String type);
+
+	/**
+	   * sets this EmailSchema's format property to the given format and
+	   * returns this instance of EmailSchema
+	   *
+	   * @param String format
+	   * @return EmailSchema
+	   */
+	EmailSchema format(String format);
+
+	/**
+	   * sets the _default property of this EmailSchema to the given _default value.
+	   * 
+	   * @param byte[] _default
+	   * @return EmailSchema
+	   */
+	EmailSchema _default(String _default);
+
+	/**
+	   * sets the _enum property of this EmailSchema to the given _enum value.
+	   * 
+	   * @param List&lt;byte[]&gt; _enum
+	   * @return EmailSchema
+	   */
+	EmailSchema _enum(List<String> _enum);
+
+	/**
+	   * Adds the given _enumItem to this EmailSchema's List of _enumItems.
+	   *
+	   * @param byte[] _enumItem
+	   */
+	EmailSchema addEnumItem(String _enumItem);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/FileSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/FileSchema.java
new file mode 100644
index 000000000..812a62b7a
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/FileSchema.java
@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+/**
+ * FileSchema
+ */
+public interface FileSchema extends Schema<String> {
+
+	/**
+	 * Sets the type property of a FileSchema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param type
+	 * @return FileSchema instance with the set type property.
+	 */
+
+	FileSchema type(String type);
+
+	/**
+	 * Sets the format property of a FileSchema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param format
+	 * @return FileSchema instance with the set format property.
+	 */
+
+	FileSchema format(String format);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/IntegerSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/IntegerSchema.java
new file mode 100644
index 000000000..82d282217
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/IntegerSchema.java
@@ -0,0 +1,84 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.List;
+
+/**
+ * IntegerSchema
+ */
+public interface IntegerSchema extends Schema<Integer> {
+
+	/**
+	 * Sets the type property for an IntegerSchema instance to the
+	 * parameter and returns the instance.
+	 * Type for IntegerSchema instance is "integer"
+	 *
+	 * @param type
+	 * @return IntegerSchema instance with the set type
+	 **/
+
+	IntegerSchema type(String type);
+
+	/**
+	 * Sets the format property for an IntegerSchema instance to the
+	 * parameter and returns the instance.
+	 * The format property for IntegerSchema can be: "int32" or "int64"
+	 *
+	 * @param format
+	 * @return IntegerSchema instance with the set format
+	 **/
+
+	IntegerSchema format(String format);
+
+	/**
+	 * Sets the _default property of an IntegerSchema instance to the
+	 * parameter and returns the instance.
+	 * _default property is inherited from super class Schema
+	 * Method setDefault inherited from Schema super class.
+	 *
+	 * @param _default
+	 * @return IntegerSchema instance with the set _default
+	 * @see SchemaImpl.setDefault
+	 */
+
+	IntegerSchema _default(Integer _default);
+
+	/**
+	 * Sets inherited _enum property of an IntegerSchema instance to the
+	 * parameter.
+	 * _enum is inherited from Schema.
+	 *
+	 * @param _enum
+	 * @return IntegerSchema instance with the set _enum
+	 * @see SchemaImpl
+	 */
+
+	IntegerSchema _enum(List<Integer> _enum);
+
+	/**
+	 * Adds an item to _enum List.
+	 * If _enum is null, will create a new ArrayList and add the item.
+	 *
+	 * @param _enumItem
+	 * @return IntegerSchema instance with modified _enum
+	 */
+
+	IntegerSchema addEnumItem(Integer _enumItem);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MapSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MapSchema.java
new file mode 100644
index 000000000..d2da1eb65
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MapSchema.java
@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+/**
+ * MapSchema
+ */
+public interface MapSchema extends Schema {
+
+	/**
+	 * Sets type property of MapSchema instance to the
+	 * parameter and returns the instance.
+	 *
+	 * @param type
+	 * @return MapSchema instance with the modified type property
+	 */
+
+	MapSchema type(String type);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/NumberSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/NumberSchema.java
new file mode 100644
index 000000000..c5be14c6f
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/NumberSchema.java
@@ -0,0 +1,73 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.math.BigDecimal;
+import java.util.List;
+
+/**
+ * NumberSchema
+ */
+public interface NumberSchema extends Schema<BigDecimal> {
+
+	/**
+	 * Sets the type property of a NumberSchema instance
+	 * to the parameter.
+	 *
+	 * @param type
+	 * @return NumberSchema instance with the modified type property
+	 */
+
+	NumberSchema type(String type);
+
+	/**
+	 * Sets the _default property of a NumberSchema instance
+	 * to the parameter and returns the instance.
+	 * _default property is inherited from super class Schema
+	 * Method setDefault inherited from Schema super class.
+	 *
+	 * @param _default
+	 * @return The instance of NumberSchema with the modified _default
+	 * @see SchemaImpl.setDefault
+	 */
+
+	NumberSchema _default(BigDecimal _default);
+
+	/**
+	 * Sets inherited _enum property of a NumberSchema instance
+	 * to the parameter.
+	 * _enum is inherited from Schema.
+	 *
+	 * @param _enum A list of BigDecimal values
+	 * @return A NumberSchema instance with the set _enum
+	 * @see SchemaImpl
+	 */
+
+	NumberSchema _enum(List<BigDecimal> _enum);
+
+	/**
+	 * Adds an item to _enum List.
+	 * If _enum is null, will create a new ArrayList and add the item.
+	 *
+	 * @param BigDecimal _enumItem
+	 * @return NumberSchema instance with the modified _enum item
+	 */
+
+	NumberSchema addEnumItem(BigDecimal _enumItem);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ObjectSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ObjectSchema.java
new file mode 100644
index 000000000..d4ced325a
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ObjectSchema.java
@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+/**
+ * ObjectSchema
+ */
+public interface ObjectSchema extends Schema<Object> {
+
+	/**
+	 * Sets the type property of ObjectSchema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param type
+	 * @return ObjectSchema instance with modified type property
+	 */
+
+	ObjectSchema type(String type);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/PasswordSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/PasswordSchema.java
new file mode 100644
index 000000000..2115d31f9
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/PasswordSchema.java
@@ -0,0 +1,80 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.List;
+
+/**
+ * PasswordSchema
+ */
+public interface PasswordSchema extends Schema<String> {
+
+	/**
+	 * Sets the type property of a PasswordSchema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param type
+	 * @return PasswordSchema instance with the modified type property
+	 */
+
+	PasswordSchema type(String type);
+
+	/**
+	 * Sets the format property for a PasswordSchema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param format
+	 * @return PasswordSchema instance with modified format
+	 **/
+
+	PasswordSchema format(String format);
+
+	/**
+	 * Sets the inherited _default property of a PasswordSchema instance
+	 * to the parameter and returns the instance.
+	 * _default is inherited from Schema.
+	 *
+	 * @param _default
+	 * @return The instance of PasswordSchema with the set _default
+	 */
+
+	PasswordSchema _default(String _default);
+
+	/**
+	 * Sets inherited _enum property of a PasswordSchema instance
+	 * to the parameter.
+	 * _enum is inherited from Schema.
+	 *
+	 * @param _enum
+	 * @return A PasswordSchema instance with set _enum
+	 * @see SchemaImpl
+	 */
+
+	PasswordSchema _enum(List<String> _enum);
+
+	/**
+	 * Adds an item to _enum List.
+	 * If _enum is null, will create a new ArrayList and add the item.
+	 *
+	 * @param _enumItem to be added to the _enum List
+	 * @return PasswordSchema instance with the modified _enum
+	 */
+
+	PasswordSchema addEnumItem(String _enumItem);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/StringSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/StringSchema.java
new file mode 100644
index 000000000..542411684
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/StringSchema.java
@@ -0,0 +1,76 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.List;
+
+/**
+ * StringSchema
+ */
+public interface StringSchema extends Schema<String> {
+
+	/**
+	 * Sets the type property of a StringSchema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param type
+	 * @return StringSchema instance with modified type property.
+	 */
+
+	StringSchema type(String type);
+
+	/**
+	 * Sets inherited _default property of a StringSchema instance
+	 * to the parameter and returns the instance.
+	 * _default is inherited from super class Schema
+	 *
+	 * @param _default
+	 * @return StringSchema instance with the modified _default property
+	 * @see SchemaImpl
+	 */
+
+	StringSchema _default(String _default);
+
+	/**
+	 * Sets inherited _enum property of a StringSchema instance
+	 * to the parameter.
+	 * <p>
+	 * _enum is inherited from super class Schema.
+	 * <p>
+	 * Uses super class method setEnum() and returns
+	 * the instance.
+	 *
+	 * @param _enum
+	 * @return StringSchema instance with modified _enum.
+	 * @see SchemaImpl
+	 */
+
+	StringSchema _enum(List<String> _enum);
+
+	/**
+	 * Adds an item to _enum of a StringSchema instance
+	 * and returns the instance.
+	 * If _enum is null, creates a new ArrayList and adds item.
+	 *
+	 * @param _enumItem
+	 * @return StringSchema instance with the added _enum item.
+	 */
+
+	StringSchema addEnumItem(String _enumItem);
+
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/UUIDSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/UUIDSchema.java
new file mode 100644
index 000000000..ec66699a3
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/UUIDSchema.java
@@ -0,0 +1,101 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models.media;
+
+import java.util.List;
+import java.util.UUID;
+
+/**
+ * UUIDSchema
+ */
+public interface UUIDSchema extends Schema<UUID> {
+
+	/**
+	 * Sets the type property of a UUIDSchema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param type
+	 * @return UUIDSchema instance with modified type property.
+	 */
+
+	UUIDSchema type(String type);
+
+	/**
+	 * Sets format property of a UUIDSchema instance
+	 * to the parameter and returns the instance.
+	 *
+	 * @param format
+	 * @return UUIDSchema instance with the modified format
+	 */
+
+	UUIDSchema format(String format);
+
+	/**
+	 * Sets inherited _default property of a UUIDSchema instance
+	 * to the parameter and returns the instance.
+	 * _default is inherited from super class Schema
+	 *
+	 * <p>
+	 * Sets _default from UUID argument
+	 *
+	 * @param _default
+	 * @return UUIDSchema instance with the modified _default property
+	 * @see SchemaImpl
+	 */
+
+	UUIDSchema _default(UUID _default);
+
+	/**
+	 * Sets inherited _default property of a UUIDSchema instance
+	 * to the parameter and returns the instance.
+	 * _default is inherited from super class Schema
+	 *
+	 * <p>
+	 * Sets _default from String argument
+	 *
+	 * @param _default
+	 * @return UUIDSchema instance with the modified _default property
+	 * @see SchemaImpl
+	 */
+
+	UUIDSchema _default(String _default);
+
+	/**
+	 * Sets inherited _enum property of a UUIDSchema instance
+	 * to the parameter.
+	 * _enum is inherited from super class Schema.
+	 *
+	 * @param _enum
+	 * @return UUIDSchema instance with modified _enum.
+	 * @see SchemaImpl
+	 */
+
+	UUIDSchema _enum(List<UUID> _enum);
+
+	/**
+	 * Adds an item to _enum of a UUIDSchema instance
+	 * to the parameter and returns the instance.
+	 * If _enum is null, creates a new ArrayList and adds item.
+	 *
+	 * @param _enumItem
+	 * @return UUIDSchema instance with the added _enum item.
+	 */
+
+	UUIDSchema addEnumItem(UUID _enumItem);
+
+}
\ No newline at end of file

From 4ade267c56d42fa7194f1ea35307ef53fea19216 Mon Sep 17 00:00:00 2001
From: Michael Glavassevich <mrglavas@ca.ibm.com>
Date: Thu, 19 Oct 2017 13:40:56 -0400
Subject: [PATCH 04/23] Factoring out a base interface for extension related
 methods.

Signed-off-by: Michael Glavassevich <mrglavas@ca.ibm.com>
---
 .../openapi/models/Components.java            | 25 +---------
 .../openapi/models/Extensible.java            | 50 +++++++++++++++++++
 .../openapi/models/ExternalDocumentation.java | 27 +---------
 .../microprofile/openapi/models/OpenAPI.java  | 26 +---------
 .../openapi/models/Operation.java             | 25 +---------
 .../microprofile/openapi/models/PathItem.java | 24 +--------
 .../microprofile/openapi/models/Paths.java    | 25 +---------
 .../openapi/models/callbacks/Callback.java    | 26 +---------
 .../openapi/models/examples/Example.java      | 27 +---------
 .../openapi/models/headers/Header.java        | 25 +---------
 .../openapi/models/info/Contact.java          | 27 +---------
 .../openapi/models/info/Info.java             | 27 +---------
 .../openapi/models/info/License.java          | 32 +++---------
 .../openapi/models/links/Link.java            | 25 +---------
 .../openapi/models/links/LinkParameter.java   | 27 +---------
 .../openapi/models/media/Encoding.java        | 25 +---------
 .../openapi/models/media/MediaType.java       | 33 +-----------
 .../openapi/models/media/Schema.java          | 29 +----------
 .../openapi/models/media/XML.java             | 32 +-----------
 .../openapi/models/parameters/Parameter.java  | 32 +-----------
 .../models/parameters/RequestBody.java        | 32 +-----------
 .../openapi/models/responses/ApiResponse.java | 33 +-----------
 .../openapi/models/security/OAuthFlow.java    | 35 +------------
 .../openapi/models/security/OAuthFlows.java   | 33 +-----------
 .../openapi/models/security/Scopes.java       | 31 +-----------
 .../models/security/SecurityScheme.java       | 33 +-----------
 .../openapi/models/servers/Server.java        | 33 +-----------
 .../models/servers/ServerVariable.java        | 32 +-----------
 .../models/servers/ServerVariables.java       |  9 +---
 .../microprofile/openapi/models/tags/Tag.java | 33 +-----------
 30 files changed, 107 insertions(+), 766 deletions(-)
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/Extensible.java

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 d22edc46c..6f332473d 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
@@ -34,7 +34,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#componentsObject"
  */
-public interface Components extends Constructible {
+public interface Components extends Constructible, Extensible {
 
 	/**
 	 * returns the schemas property from a Components instance.
@@ -330,27 +330,4 @@ public interface Components extends Constructible {
 	 */
 	Components addCallbacks(String key, Callback callbacksItem);
 
-	/**
-	 * returns the extensions property from a Components instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 **/
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds the given Object to this Components' map of extensions, with the given key as its key.
-	 *
-	 * @param String key
-	 * @param Object value
-	 * @return Components
-	 */
-	void addExtension(String name, Object value);
-
-	/**
-	 * sets this Components' extensions property to the given map of extensions.
-	 *
-	 * @param Map&lt;String, Object&gt;extensions
-	 */
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
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
new file mode 100644
index 000000000..78d567617
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Extensible.java
@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models;
+
+import java.util.Map;
+
+/**
+ * Base interface for OpenAPI model objects that can contain extensions.
+ */
+public interface Extensible {
+	
+	/**
+	 * Returns the extensions property from an Extensible instance.
+	 *
+	 * @return Map&lt;String, Object&gt; extensions
+	 **/
+	Map<String, Object> getExtensions();
+
+	/**
+	 * Adds the given Object to this Extensible's map of extensions, with the given name as its key.
+	 *
+	 * @param String name
+	 * @param Object value
+	 * @return Components
+	 */
+	void addExtension(String name, Object value);
+
+	/**
+	 * Sets this Extensible's extensions property to the given map of extensions.
+	 *
+	 * @param Map&lt;String, Object&gt;extensions
+	 */
+	void setExtensions(Map<String, Object> extensions);
+
+}
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
index 8bc22bdf0..690fc5573 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
@@ -17,14 +17,12 @@
 
 package org.eclipse.microprofile.openapi.models;
 
-import java.util.Map;
-
 /**
  * ExternalDocumentation
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#externalDocumentationObject"
  */
-public interface ExternalDocumentation extends Constructible {
+public interface ExternalDocumentation extends Constructible, Extensible {
 
 	/**
 	   * returns the description property from a ExternalDocumentation instance.
@@ -74,27 +72,4 @@ public interface ExternalDocumentation extends Constructible {
 	   */
 	ExternalDocumentation url(String url);
 
-	/**
-	   * returns the extensions property from a ExternalDocumentation instance.
-	   *
-	   * @return Map&lt;String, Object&gt;extensions
-	   **/
-	Map<String, Object> getExtensions();
-
-	/**
-	   * Adds the given extension to this ExternalDocumentation's map of extensions, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param Object value
-	   * @return Components
-	   */
-	void addExtension(String name, Object value);
-
-	/**
-	   * sets this ExternalDocumentation's extensions property to the given extensions.
-	   *
-	   * @param Map&lt;String, Object&gt;extensions
-	   */
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
index e750b8102..c568cd710 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
@@ -18,7 +18,6 @@
 package org.eclipse.microprofile.openapi.models;
 
 import java.util.List;
-import java.util.Map;
 
 import org.eclipse.microprofile.openapi.models.info.Info;
 import org.eclipse.microprofile.openapi.models.media.Schema;
@@ -32,7 +31,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md"
  */
-public interface OpenAPI extends Constructible {
+public interface OpenAPI extends Constructible, Extensible {
 
 	/**
 	   * returns the openapi property from a OpenAPI instance.
@@ -279,27 +278,4 @@ public interface OpenAPI extends Constructible {
 	   */
 	OpenAPI schemaRequirement(String name, SecurityScheme securityScheme);
 
-	/**
-	   * returns the extensions property from a OpenAPI instance.
-	   *
-	   * @return Map&lt;String, Object&gt; extensions
-	   **/
-	Map<String, Object> getExtensions();
-
-	/**
-	   * Adds the given Object to this OpenAPI's map of extensions, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param Object value
-	   * @return OpenAPI
-	   */
-	void addExtension(String name, Object value);
-
-	/**
-	   * sets this OpenAPI's extensions property to the given map of extensions.
-	   *
-	   * @param Map&lt;String, Object&gt;extensions
-	   */
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
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 02ff7fa19..aee97e966 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
@@ -32,7 +32,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#operationObject"
  */
-public interface Operation extends Constructible {
+public interface Operation extends Constructible, Extensible {
 
 	/**
 	   * returns the tags property from a Operation instance.
@@ -357,27 +357,4 @@ public interface Operation extends Constructible {
 	   */
 	Operation addServersItem(Server serversItem);
 
-	/**
-	   * returns the extensions property from a Operation instance.
-	   *
-	   * @return Map&lt;String, Object&gt; extensions
-	   **/
-	Map<String, Object> getExtensions();
-
-	/**
-	   * Adds the given Object to this Operation's map of extensions, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param Object value
-	   * @return Operation
-	   */
-	void addExtension(String name, Object value);
-
-	/**
-	   * sets this Operation's extensions property to the given map of extensions.
-	   *
-	   * @param Map&lt;String, Object&gt;extensions
-	   */
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
index f93fa6b26..b32d911f4 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
@@ -28,7 +28,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#pathItemObject"
  */
-public interface PathItem extends Constructible {
+public interface PathItem extends Constructible, Extensible {
 
 	/**
 	 * All of the possible types of methods for this path
@@ -363,28 +363,6 @@ enum HttpMethod {
 	*/
 	PathItem addParametersItem(Parameter parametersItem);
 
-	/**
-	 * returns the extensions property from a PathItem instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 **/
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds the given extension to this PathItem's list of extension, with the given key as its key.
-	 *
-	 * @param String key
-	 * @param Object value
-	*/
-	void addExtension(String name, Object value);
-
-	/**
-	 * sets this PathItem's patch extensions to the given extensions
-	 *
-	 * @param Map&lt;String, Object&gt; extensions
-	 **/
-	void setExtensions(Map<String, Object> extensions);
-
 	/**
 	 * returns the ref property from a PathItem instance.
 	 *
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 c50554aa6..a1db22108 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
@@ -24,7 +24,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#pathsObject"
  */
-public interface Paths extends Constructible, Map<String, PathItem> {
+public interface Paths extends Constructible, Extensible, Map<String, PathItem> {
 
 	/**
 	   * Adds the given path item to this Paths and return this instance of Paths
@@ -35,27 +35,4 @@ public interface Paths extends Constructible, Map<String, PathItem> {
 	   */
 	Paths addPathItem(String name, PathItem item);
 
-	/**
-	   * returns the extensions property from a Paths instance.
-	   *
-	   * @return Map&lt;String, Object&gt; extensions
-	   **/
-	Map<String, Object> getExtensions();
-
-	/**
-	   * Adds the given Object to this Paths' map of extensions, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param Object value
-	   * @return Paths
-	   */
-	void addExtension(String name, Object value);
-
-	/**
-	   * sets this Paths' extensions property to the given map of extensions.
-	   *
-	   * @param Map&lt;String, Object&gt;extensions
-	   */
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
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 282d34e07..d63e64cef 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
@@ -20,6 +20,7 @@
 import java.util.Map;
 
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 import org.eclipse.microprofile.openapi.models.PathItem;
 
 /**
@@ -27,7 +28,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#callbackObject"
  */
-public interface Callback extends Constructible, Map<String, PathItem> {
+public interface Callback extends Constructible, Extensible, Map<String, PathItem> {
 
 	/**
 	   * Adds the given PathItem to this Callbacks's list of PathItems, with the given key as its key.
@@ -37,27 +38,4 @@ public interface Callback extends Constructible, Map<String, PathItem> {
 	   */
 	Callback addPathItem(String name, PathItem item);
 
-	/**
-	   * returns the extensions property from a Callback instance.
-	   *
-	   * @return Map&lt;String, Object&gt; extensions
-	   **/
-	Map<String, Object> getExtensions();
-
-	/**
-	   * Adds the given Object to this Callback's map of extensions, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param Object value
-	   * @return Components
-	   */
-	void addExtension(String name, Object value);
-
-	/**
-	   * sets this Components' extensions property to the given map of extensions.
-	   *
-	   * @param Map&lt;String, Object&gt;extensions
-	   */
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
index 61f4a880d..094674d77 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
@@ -17,14 +17,13 @@
 
 package org.eclipse.microprofile.openapi.models.examples;
 
-import java.util.Map;
-
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
  * Example
  */
-public interface Example extends Constructible {
+public interface Example extends Constructible, Extensible {
 
 	/**
 	 * returns the summary property from a Example instance.
@@ -145,26 +144,4 @@ public interface Example extends Constructible {
 	 */
 	Example $ref(String $ref);
 
-	/**
-	 * returns the extensions property from a Example instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 **/
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds the given Object to this Example's map of extensions, with the given key as its key.
-	 *
-	 * @param String key
-	 * @param Object value
-	 */
-	void addExtension(String name, Object value);
-
-	/**
-	 * sets the extensions property for a Example instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 **/
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
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 cf6e5ee01..dc1947bc8 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
@@ -20,11 +20,12 @@
 import java.util.Map;
 
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 import org.eclipse.microprofile.openapi.models.examples.Example;
 import org.eclipse.microprofile.openapi.models.media.Content;
 import org.eclipse.microprofile.openapi.models.media.Schema;
 
-public interface Header extends Constructible {
+public interface Header extends Constructible, Extensible {
 	
     /**
      * Gets or Sets style
@@ -297,28 +298,6 @@ public String toString() {
 	 */
 	Header content(Content content);
 
-	/**
-	 * returns the extensions property from a Header instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds the given Object to this Header's map of extensions, with the given key as its key.
-	 *
-	 * @param String key
-	 * @param Object value
-	 */
-	void addExtension(String name, Object value);
-
-	/**
-	 * sets the extensions property for a Header instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-	void setExtensions(Map<String, Object> extensions);
-
 	/**
 	 * returns the $ref property from a Header instance.
 	 *
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java
index 881e4ac54..cb8f65f09 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java
@@ -17,16 +17,15 @@
 
 package org.eclipse.microprofile.openapi.models.info;
 
-import java.util.Map;
-
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
  * Contact
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#contactObject"
  */
-public interface Contact extends Constructible {
+public interface Contact extends Constructible, Extensible {
 
 	/**
 	   * returns the name property from a Contact instance.
@@ -100,26 +99,4 @@ public interface Contact extends Constructible {
 	   */
 	Contact email(String email);
 
-	/**
-	   * returns the extensions property from a Contact instance.
-	   *
-	   * @return Map&lt;String, Object&gt; extensions
-	   */
-	Map<String, Object> getExtensions();
-
-	/**
-	   * Adds the given Object to this Contact's map of extensions, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param Object value
-	   */
-	void addExtension(String name, Object value);
-
-	/**
-	    * sets the extensions property for a Contact instance.
-	    *
-	    * @return Map&lt;String, Object&gt; extensions
-	    */
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
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 93ac273fa..0c5190dc9 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
@@ -17,15 +17,14 @@
 
 package org.eclipse.microprofile.openapi.models.info;
 
-import java.util.Map;
-
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
 *
 * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#infoObject"
 */
-public interface Info extends Constructible {
+public interface Info extends Constructible, Extensible {
 
 	/**
 	   * returns the title property from a Info instance.
@@ -171,26 +170,4 @@ public interface Info extends Constructible {
 	   */
 	Info version(String version);
 
-	/**
-	   * returns the extensions property from a Info instance.
-	   *
-	   * @return Map&lt;String, Object&gt; extensions
-	   */
-	Map<String, Object> getExtensions();
-
-	/**
-	   * Adds the given Object to this Info's map of extensions, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param Object value
-	   */
-	void addExtension(String name, Object value);
-
-	/**
-	    * sets the extensions property for a Info instance.
-	    *
-	    * @return Map&lt;String, Object&gt; extensions
-	    */
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
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 951c04807..b86ad8d00 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
@@ -17,11 +17,15 @@
 
 package org.eclipse.microprofile.openapi.models.info;
 
-import java.util.Map;
-
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 
-public interface License extends Constructible {
+/**
+ * License
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#licenseObject"
+ */
+public interface License extends Constructible, Extensible {
 
 	/**
 	   * returns the name property from a License instance.
@@ -71,26 +75,4 @@ public interface License extends Constructible {
 	   */
 	License url(String url);
 
-	/**
-	   * returns the extensions property from a License instance.
-	   *
-	   * @return Map&lt;String, Object&gt; extensions
-	   */
-	Map<String, Object> getExtensions();
-
-	/**
-	   * Adds the given Object to this License's map of extensions, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param Object value
-	   */
-	void addExtension(String name, Object value);
-
-	/**
-	   * sets the extensions property for a License instance.
-	   *
-	   * @return Map&lt;String, Object&gt; extensions
-	   */
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
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 4b9027ee6..4dd34add0 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
@@ -20,6 +20,7 @@
 import java.util.Map;
 
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 import org.eclipse.microprofile.openapi.models.headers.Header;
 import org.eclipse.microprofile.openapi.models.parameters.RequestBody;
 import org.eclipse.microprofile.openapi.models.servers.Server;
@@ -29,7 +30,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#linkObject"
  */
-public interface Link extends Constructible {
+public interface Link extends Constructible, Extensible {
 
 	/**
 	 * returns the server property from a Link instance.
@@ -230,26 +231,4 @@ public interface Link extends Constructible {
 	 */
 	Link $ref(String $ref);
 
-	/**
-	 * returns the extensions property from a Link instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds the given Object to this Link's map of extensions, with the given name as its key.
-	 *
-	 * @param String key
-	 * @param Object value
-	 */
-	void addExtension(String name, Object value);
-
-	/**
-	 * sets the extensions property for a Link instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/links/LinkParameter.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/links/LinkParameter.java
index 4b0a0e299..82e33a0b2 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/links/LinkParameter.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/links/LinkParameter.java
@@ -17,16 +17,15 @@
 
 package org.eclipse.microprofile.openapi.models.links;
 
-import java.util.Map;
-
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
  * LinkParameter
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#linkOParametersbject"
  */
-public interface LinkParameter extends Constructible {
+public interface LinkParameter extends Constructible, Extensible {
 
 	/**
 	   * returns the value property from a LinkParameter instance.
@@ -51,26 +50,4 @@ public interface LinkParameter extends Constructible {
 	   */
 	LinkParameter value(String value);
 
-	/**
-	   * returns the extensions property from a LinkParameter instance.
-	   *
-	   * @return Map&lt;String, Object&gt; extensions
-	   */
-	Map<String, Object> getExtensions();
-
-	/**
-	   * Adds the given Object to this LinkParameter's map of extensions, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param Object value
-	   */
-	void addExtension(String name, Object value);
-
-	/**
-	   * sets the extensions property for a LinkParameter instance.
-	   *
-	   * @return Map&lt;String, Object&gt; extensions
-	   */
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
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 52eb5b0b3..123750da0 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
@@ -20,6 +20,7 @@
 import java.util.Map;
 
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 import org.eclipse.microprofile.openapi.models.headers.Header;
 
 /**
@@ -27,7 +28,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#encodingObject"
  */
-public interface Encoding extends Constructible {
+public interface Encoding extends Constructible, Extensible {
 
 	enum StyleEnum {
 	    FORM("form"),
@@ -162,26 +163,4 @@ public String toString() {
 	 */
 	void setAllowReserved(Boolean allowReserved);
 
-	/**
-	 * returns the extensions property from a Encoding instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 **/
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds the given extension value to this Encoding's map of extensions, with the given name as its key.
-	 *
-	 * @param String name
-	 * @param Object value
-	 */
-	void addExtension(String name, Object value);
-
-	/**
-	 * sets this Encoding's extensions property to the given extensions.
-	 *
-	 * @param Map&lt;String, Object&gt; extensions
-	 */
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
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 9fff6d233..e17f7081e 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
@@ -20,6 +20,7 @@
 import java.util.Map;
 
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 import org.eclipse.microprofile.openapi.models.examples.Example;
 
 /**
@@ -27,7 +28,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#mediaTypeObject"
  */
-public interface MediaType extends Constructible {
+public interface MediaType extends Constructible, Extensible {
 
 	/**
 	 * returns the schema property from a MediaType instance.
@@ -165,34 +166,4 @@ public interface MediaType extends Constructible {
 
 	MediaType addEncoding(String key, Encoding encodingItem);
 
-	/**
-	 * Returns extensions property of a MediaType instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds an object item to extensions map for
-	 * the specified name key.
-	 * <p>
-	 * If the extensions property is null, creates a new HashMap
-	 * and adds the item to it.
-	 *
-	 * @param name - map key
-	 * @param value - map value
-	 */
-
-	void addExtension(String name, Object value);
-
-	/**
-	 * Sets extensions property of a MediaType instance
-	 * to the parameter.
-	 *
-	 * @param extensions
-	 */
-
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
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 12811eef3..ad1c7493e 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
@@ -22,6 +22,7 @@
 import java.util.Map;
 
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 import org.eclipse.microprofile.openapi.models.ExternalDocumentation;
 
 /**
@@ -29,7 +30,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#schemaObject"
  */
-public interface Schema<T> extends Constructible {
+public interface Schema<T> extends Constructible, Extensible {
 
 	/**
 	 * returns the name property from a from a Schema instance. Ignored in serialization.
@@ -948,30 +949,4 @@ public interface Schema<T> extends Constructible {
 
 	Schema xml(XML xml);
 
-	/**
-	 * Returns extensions property of a Schema instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds an object item to extensions map at
-	 * the specified key.
-	 *
-	 * @param name - map key
-	 * @param value - map value
-	 */
-
-	void addExtension(String name, Object value);
-
-	/**
-	 * Sets extensions property of a Schema instance
-	 *
-	 * @param extensions
-	 */
-
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java
index 4f13f123e..c48527947 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java
@@ -17,16 +17,15 @@
 
 package org.eclipse.microprofile.openapi.models.media;
 
-import java.util.Map;
-
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
  * XML
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#xmlObject"
  */
-public interface XML extends Constructible {
+public interface XML extends Constructible, Extensible {
 
 	/**
 	 * returns the name property from a XML instance.
@@ -163,31 +162,4 @@ public interface XML extends Constructible {
 
 	XML wrapped(Boolean wrapped);
 
-	/**
-	 * Returns the extensions property of an XML instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds an item to the extensions property of an XML instance.
-	 * If extensions is null, creates a HashMap and adds item to it.
-	 *
-	 * @param name - map key
-	 * @param value - map value
-	 */
-
-	void addExtension(String name, Object value);
-
-	/**
-	 * Sets the extensions property of an XML instance
-	 * to the parameter.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
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 4996aba56..355a28d6e 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
@@ -19,6 +19,7 @@
 
 import java.util.Map;
 
+import org.eclipse.microprofile.openapi.models.Extensible;
 import org.eclipse.microprofile.openapi.models.examples.Example;
 import org.eclipse.microprofile.openapi.models.media.Content;
 import org.eclipse.microprofile.openapi.models.media.Schema;
@@ -28,7 +29,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#parameterObject"
  */
-public interface Parameter {
+public interface Parameter extends Extensible {
 
 	/**
 	 * Gets or Sets style
@@ -438,33 +439,4 @@ public String toString() {
 
 	Parameter $ref(String $ref);
 
-	/**
-	 * Returns extensions property of a Parameter instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds an object item to extensions map at
-	 * the specified key.
-	 * <p>
-	 * If extensions is null, creates a new HashMap
-	 * and adds item to it
-	 *
-	 * @param String name - map key
-	 * @param Object value - map value
-	 */
-
-	void addExtension(String name, Object value);
-
-	/**
-	 * Sets extensions property of a Parameter instance
-	 *
-	 * @param Map&lt;String, Object&gt; extensions
-	 */
-
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java
index 29c1a4b67..93df4a6c6 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java
@@ -17,9 +17,8 @@
 
 package org.eclipse.microprofile.openapi.models.parameters;
 
-import java.util.Map;
-
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 import org.eclipse.microprofile.openapi.models.media.Content;
 
 /**
@@ -27,7 +26,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#requestBodyObject"
  */
-public interface RequestBody extends Constructible {
+public interface RequestBody extends Constructible, Extensible {
 
 	/**
 	 * returns the description property from a RequestBody instance.
@@ -110,33 +109,6 @@ public interface RequestBody extends Constructible {
 
 	RequestBody required(Boolean required);
 
-	/**
-	 * Returns extensions property of a RequestBody instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds an object item to extensions map at
-	 * the specified key.
-	 *
-	 * @param name - map key
-	 * @param value - map value
-	 */
-
-	void addExtension(String name, Object value);
-
-	/**
-	 * Sets extensions property of a RequestBody instance
-	 * to the parameter.
-	 *
-	 * @param extensions
-	 */
-
-	void setExtensions(Map<String, Object> extensions);
-
 	/**
 	 * returns the $ref property from a RequestBody instance.
 	 *
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 817a967b4..5a4f7f8d9 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
@@ -20,6 +20,7 @@
 import java.util.Map;
 
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 import org.eclipse.microprofile.openapi.models.headers.Header;
 import org.eclipse.microprofile.openapi.models.links.Link;
 import org.eclipse.microprofile.openapi.models.media.Content;
@@ -29,7 +30,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#responseObject"
  */
-public interface ApiResponse extends Constructible {
+public interface ApiResponse extends Constructible, Extensible {
 
 	/**
 	 * returns the description property from a ApiResponse instance.
@@ -181,34 +182,4 @@ public interface ApiResponse extends Constructible {
 
 	ApiResponse $ref(String $ref);
 
-	/**
-	 * Returns extensions property of a ApiResponse instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds an object item to extensions map at
-	 * the specified key.
-	 * <p>
-	 * If extensions is null, creates a new HashMap
-	 * and adds item to it
-	 *
-	 * @param name - map key
-	 * @param value - map value
-	 */
-
-	void addExtension(String name, Object value);
-
-	/**
-	 * Sets extensions property of a ApiResponse instance
-	 * to the parameter.
-	 *
-	 * @param extensions
-	 */
-
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java
index 39de69773..be0a0c464 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java
@@ -17,16 +17,15 @@
 
 package org.eclipse.microprofile.openapi.models.security;
 
-import java.util.Map;
-
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
  * OAuthFlow
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#oauthFlowsObject"
  */
-public interface OAuthFlow extends Constructible {
+public interface OAuthFlow extends Constructible, Extensible {
 
 	/**
 	 * returns the authorizationUrl property from a OAuthFlow instance.
@@ -135,34 +134,4 @@ public interface OAuthFlow extends Constructible {
 
 	OAuthFlow scopes(Scopes scopes);
 
-	/**
-	 * Returns extensions property of a OAuthFlow instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds an object item to extensions map at
-	 * the specified key.
-	 * <p>
-	 * If extensions is null, creates a new HashMap
-	 * and adds item to it
-	 *
-	 * @param name - map key
-	 * @param value - map value
-	 */
-
-	void addExtension(String name, Object value);
-
-	/**
-	 * Sets extensions property of a OAuthFlow instance
-	 * to the parameter.
-	 *
-	 * @param extensions
-	 */
-
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java
index ddd00742a..b270c312d 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java
@@ -17,16 +17,15 @@
 
 package org.eclipse.microprofile.openapi.models.security;
 
-import java.util.Map;
-
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
  * OAuthFlows
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#oauthFlowsObject"
  */
-public interface OAuthFlows extends Constructible {
+public interface OAuthFlows extends Constructible, Extensible {
 
 	/**
 	 * returns the implicit property from a OAuthFlows instance.
@@ -136,32 +135,4 @@ public interface OAuthFlows extends Constructible {
 
 	OAuthFlows authorizationCode(OAuthFlow authorizationCode);
 
-	/**
-	 * Returns extensions property of an OAuthFlows instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds an object item to extensions map of an OAuthFlows instance
-	 * at the specified key.
-	 * If extensions is null, then creates a new HashMap and adds the item.
-	 *
-	 * @param name
-	 * @param value
-	 */
-
-	void addExtension(String name, Object value);
-
-	/**
-	 * Sets extensions property of an OAuthFlows instance
-	 * to the parameter.
-	 *
-	 * @param extensions
-	 */
-
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
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 8499b94a5..dea0f53b6 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
@@ -20,13 +20,14 @@
 import java.util.Map;
 
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
  * Scopes
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#scopedObject"
  */
-public interface Scopes extends Constructible, Map<String, String> {
+public interface Scopes extends Constructible, Extensible, Map<String, String> {
 
 	/**
 	 * Adds name and item parameters to a Scopes instance
@@ -39,32 +40,4 @@ public interface Scopes extends Constructible, Map<String, String> {
 
 	Scopes addString(String name, String item);
 
-	/**
-	 * Returns extensions property of an Scopes instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds an object item to extensions map of an Scopes instance
-	 * at the specified key.
-	 * If extensions is null, then creates a new HashMap and adds the item.
-	 *
-	 * @param name
-	 * @param value
-	 */
-
-	void addExtension(String name, Object value);
-
-	/**
-	 * Sets extensions property of an Scopes instance
-	 * to the parameter.
-	 *
-	 * @param extensions
-	 */
-
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java
index f4aabc8c5..ef917309a 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java
@@ -17,16 +17,15 @@
 
 package org.eclipse.microprofile.openapi.models.security;
 
-import java.util.Map;
-
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
  * SecurityScheme
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#securitySchemeObject"
  */
-public interface SecurityScheme extends Constructible {
+public interface SecurityScheme extends Constructible, Extensible {
 
 	/**
 	 * Gets or Sets type
@@ -285,34 +284,6 @@ public String toString() {
 
 	SecurityScheme openIdConnectUrl(String openIdConnectUrl);
 
-	/**
-	 * Returns extensions property of a SecurityScheme instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds an object item to extensions map of a SecurityScheme instance
-	 * at the specified key.
-	 * If extensions is null, then creates a new HashMap and adds the item.
-	 *
-	 * @param name
-	 * @param value
-	 */
-
-	void addExtension(String name, Object value);
-
-	/**
-	 * Sets extensions property of a SecurityScheme instance
-	 * to the parameter.
-	 *
-	 * @param extensions
-	 */
-
-	void setExtensions(Map<String, Object> extensions);
-
 	/**
 	 * returns the $ref property from an SecurityScheme instance.
 	 *
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 670e64f2f..7ffddb42c 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,16 +17,15 @@
 
 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;
 
 /**
  * Server
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#serverObject"
  */
-public interface Server extends Constructible  {
+public interface Server extends Constructible, Extensible {
 
 	/**
 	 * returns the url property from a Server instance.
@@ -109,32 +108,4 @@ public interface Server extends Constructible  {
 
 	Server variables(ServerVariables variables);
 
-	/**
-	 * Returns extensions property of a Server instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds an object item to extensions map of a Server instance
-	 * at the specified key.
-	 * If extensions is null, then creates a new HashMap and adds the item.
-	 *
-	 * @param name
-	 * @param value
-	 */
-
-	void addExtension(String name, Object value);
-
-	/**
-	 * Sets extensions property of a Server instance
-	 * to the parameter.
-	 *
-	 * @param extensions
-	 */
-
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java
index 1320dbc2c..899983ec2 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java
@@ -18,16 +18,16 @@
 package org.eclipse.microprofile.openapi.models.servers;
 
 import java.util.List;
-import java.util.Map;
 
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
  * ServerVariable
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#serverVariableObject"
  */
-public interface ServerVariable extends Constructible {
+public interface ServerVariable extends Constructible, Extensible {
 
 	/**
 	 * returns the _enum property from a ServerVariable instance.
@@ -122,32 +122,4 @@ public interface ServerVariable extends Constructible {
 
 	ServerVariable description(String description);
 
-	/**
-	 * Returns extensions property of a ServerVariable instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds an object item to extensions map of a ServerVariable instance
-	 * at the specified key.
-	 * If extensions is null, then creates a new HashMap and adds the item.
-	 *
-	 * @param name
-	 * @param value
-	 */
-
-	void addExtension(String name, Object value);
-
-	/**
-	 * Sets extensions property of a ServerVariable instance
-	 * to the parameter.
-	 *
-	 * @param extensions
-	 */
-
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ 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 65775e710..82fea423f 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
@@ -20,13 +20,14 @@
 import java.util.Map;
 
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
  * ServerVariables
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#serverVariablesObject"
  */
-public interface ServerVariables extends Constructible, Map<String, ServerVariable> {
+public interface ServerVariables extends Constructible, Extensible, Map<String, ServerVariable> {
 
 	/**
 	 * Adds a key-value item to a ServerVariables instance from
@@ -39,10 +40,4 @@ public interface ServerVariables extends Constructible, Map<String, ServerVariab
 
 	ServerVariables addServerVariable(String name, ServerVariable item);
 
-	Map<String, Object> getExtensions();
-
-	void addExtension(String name, Object value);
-
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
index 43b49968e..6d14c1d8b 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
@@ -17,9 +17,8 @@
 
 package org.eclipse.microprofile.openapi.models.tags;
 
-import java.util.Map;
-
 import org.eclipse.microprofile.openapi.models.Constructible;
+import org.eclipse.microprofile.openapi.models.Extensible;
 import org.eclipse.microprofile.openapi.models.ExternalDocumentation;
 
 /**
@@ -27,7 +26,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#tagObject"
  */
-public interface Tag extends Constructible {
+public interface Tag extends Constructible, Extensible {
 
 	/**
 	 * returns the name property from a Tag instance.
@@ -110,32 +109,4 @@ public interface Tag extends Constructible {
 
 	Tag externalDocs(ExternalDocumentation externalDocs);
 
-	/**
-	 * Returns extensions property of a Tag instance.
-	 *
-	 * @return Map&lt;String, Object&gt; extensions
-	 */
-
-	Map<String, Object> getExtensions();
-
-	/**
-	 * Adds an object item to extensions map of a Tag instance
-	 * at the specified key.
-	 * If extensions is null, then creates a new HashMap and adds the item.
-	 *
-	 * @param name
-	 * @param value
-	 */
-
-	void addExtension(String name, Object value);
-
-	/**
-	 * Sets extensions property of a Tag instance
-	 * to the parameter.
-	 *
-	 * @param extensions
-	 */
-
-	void setExtensions(Map<String, Object> extensions);
-
 }
\ No newline at end of file

From e31d9b197d74fb408399e1263ac0781514901375 Mon Sep 17 00:00:00 2001
From: leochr <leojc@ca.ibm.com>
Date: Tue, 24 Oct 2017 12:02:10 -0400
Subject: [PATCH 05/23] Add OAS factory and resolver

Signed-off-by: leochr <leojc@ca.ibm.com>
---
 .../microprofile/openapi/OASFactory.java      | 30 ++++++
 .../microprofile/openapi/package-info.java    | 18 ++++
 .../openapi/spi/OASFactoryResolver.java       | 92 +++++++++++++++++++
 .../openapi/spi/package-info.java             | 18 ++++
 4 files changed, 158 insertions(+)
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/package-info.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/spi/OASFactoryResolver.java
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/spi/package-info.java

diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java b/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java
new file mode 100644
index 000000000..85908f9e1
--- /dev/null
+++ b/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);
+	}
+    
+}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/package-info.java
new file mode 100644
index 000000000..38c3946d4
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/package-info.java
@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.openapi;
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/spi/OASFactoryResolver.java b/api/src/main/java/org/eclipse/microprofile/openapi/spi/OASFactoryResolver.java
new file mode 100644
index 000000000..9a8c9a286
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/spi/OASFactoryResolver.java
@@ -0,0 +1,92 @@
+/**
+ * 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.spi;
+
+import org.eclipse.microprofile.openapi.models.Constructible;
+
+import java.security.AccessController;
+import java.security.PrivilegedAction;
+import java.util.ServiceLoader;
+
+public abstract class OASFactoryResolver {
+
+	private static volatile OASFactoryResolver instance = null;
+	
+	public abstract <T extends Constructible> T createObject(Class<T> clazz);
+	
+	public static OASFactoryResolver instance() {
+		if (instance == null) {
+			synchronized (OASFactoryResolver.class) {
+				if (instance != null) {
+					return instance;
+				}
+
+				ClassLoader cl = AccessController.doPrivileged(new PrivilegedAction<ClassLoader>() {
+					@Override
+					public ClassLoader run() {
+						return Thread.currentThread().getContextClassLoader();
+					}
+				});
+				if (cl == null) {
+					cl = OASFactoryResolver.class.getClassLoader();
+				}
+
+				OASFactoryResolver newInstance = loadSpi(cl);
+
+				if (newInstance == null) {
+					throw new IllegalStateException("No OASFactoryResolver implementation found!");
+				}
+
+				instance = newInstance;
+			}
+		}
+
+		return instance;
+	}
+
+	private static OASFactoryResolver loadSpi(ClassLoader cl) {
+		if (cl == null) {
+			return null;
+		}
+		
+		OASFactoryResolver instance = loadSpi(cl.getParent());
+
+		if (instance == null) {
+			ServiceLoader<OASFactoryResolver> sl = ServiceLoader.load(OASFactoryResolver.class, cl);
+			for (OASFactoryResolver spi : sl) {
+				if (instance != null) {
+					throw new IllegalStateException("Multiple OASFactoryResolver implementations found: "
+							+ spi.getClass().getName() + " and " + instance.getClass().getName());
+				} else {
+					instance = spi;
+				}
+			}
+		}
+		return instance;
+	}
+
+	/**
+	 * Set the instance. It is used by OSGi environment while service loader
+	 * pattern is not supported.
+	 *
+	 * @param factory
+	 *            set the instance.
+	 */
+	public static void setInstance(OASFactoryResolver factory) {
+		instance = factory;
+	}
+}
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/spi/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/spi/package-info.java
new file mode 100644
index 000000000..6d7504ee6
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/spi/package-info.java
@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.openapi.spi;
\ No newline at end of file

From 60f8e65b45b6611d8eabce7ab974dc9f71e3f1b9 Mon Sep 17 00:00:00 2001
From: janamanoharan <jana.manoharan96@gmail.com>
Date: Fri, 20 Oct 2017 11:15:13 -0400
Subject: [PATCH 06/23] added docs for Info, License, Contact

Signed-off-by: janamanoharan <jana.manoharan96@gmail.com>
---
 .../openapi/models/info/Contact.java          |  52 ++++-----
 .../openapi/models/info/Info.java             | 101 +++++++++---------
 2 files changed, 78 insertions(+), 75 deletions(-)

diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java
index cb8f65f09..15ebd7653 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java
@@ -21,81 +21,81 @@
 import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
- * Contact
+ * This interface represents the Contact information for the exposed API.
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#contactObject"
  */
 public interface Contact extends Constructible, Extensible {
 
 	/**
-	   * returns the name property from a Contact instance.
+	   * Returns the identifying name of this Contact instance.
 	   *
-	   * @return String name
+	   * @return the name of the contact person/organization
 	   **/
-
 	String getName();
 
 	/**
-	   * sets this Contact's name property to the given name.
+	   * Sets the identifying name of this Contact instance.
 	   *
-	   * @param String name
+	   * @param name the name of the contact person/organization
 	   */
 	void setName(String name);
 
 	/**
-	   * sets this Contact's name property to the given name and
-	   * returns this instance of Contact
+	   * Sets this Contact instance's identifying name to the given name and
+	   * returns this instance of Contact.
 	   *
-	   * @param String name
-	   * @return Contact
+	   * @param name the name of the contact person/organization
+	   * @return this Contact instance
 	   */
 	Contact name(String name);
 
 	/**
-	   * returns the url property from a Contact instance.
+	   * Returns the URL pointing to the contact information for this Contact instance.
 	   *
-	   * @return String url
+	   * @return the URL pointing to the contact information
 	   **/
 
 	String getUrl();
 
 	/**
-	   * sets this Contact's url property to the given url.
-	   *
-	   * @param String url
+       * Sets this Contact instance's URL pointing to the contact information.
+       * The URL must be in the format of a URL.
+       *
+	   * @param url the URL pointing to the contact information
 	   */
 	void setUrl(String url);
 
 	/**
-	   * sets this Contact's url property to the given url and
-	   * returns this instance of Contact
+	   * Sets this Contact instance's URL pointing to the contact information and
+	   * returns this instance of Contact. The URL must be in the format of a URL.
 	   *
-	   * @param String url
-	   * @return Contact
+	   * @param url the url pointing to the contact information
+	   * @return this Contact instance
 	   */
 	Contact url(String url);
 
 	/**
-	   * returns the email property from a Contact instance.
+	   * Returns the contact email of this Contact instance.
 	   *
-	   * @return String email
+	   * @return the email of the contact person/organization
 	   **/
 
 	String getEmail();
 
 	/**
-	   * sets this Contact's email property to the given email.
+	   * Sets the contact email of this instance of Contact.
 	   *
-	   * @param String email
+	   * @param email the email of the contact person/organization
 	   */
 	void setEmail(String email);
 
 	/**
-	   * sets this Contact's email property to the given email and
+	   * Sets this Contact instance's contact email to the given email and
 	   * returns this instance of Contact
 	   *
-	   * @param String email
-	   * @return Contact
+	   * @param email the email of the contact person/organization
+	   * @return this Contact instance
 	   */
 	Contact email(String email);
 
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 0c5190dc9..477cf9d64 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
@@ -21,152 +21,155 @@
 import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
-*
-* @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#infoObject"
-*/
+ * This interface represents all the metadata about the API. The metadata may be used by clients if needed,
+ * and may be presented in editing or documentation tools.
+ *
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#infoObject"
+ */
 public interface Info extends Constructible, Extensible {
 
 	/**
-	   * returns the title property from a Info instance.
+	   * Returns the title for the application for this instance of Info
 	   *
-	   * @return String title
+	   * @return the title of the application
 	   **/
 
 	String getTitle();
 
 	/**
-	   * sets this Info's title property to the given title.
+	   * Sets this Info instance's title for the application to the given title.
 	   *
-	   * @param String title
+	   * @param title the title of the application
 	   */
 	void setTitle(String title);
 
 	/**
-	   * sets this Info's title property to the given title and
+	   * Sets this Info instance's title for the application to the given title and
 	   * returns this instance of Info
 	   *
-	   * @param String title
-	   * @return Info
+	   * @param title the title of the application
+	   * @return this Info instance
 	   */
 	Info title(String title);
 
 	/**
-	   * returns the description property from a Info instance.
+	   * Returns a short description for the application for this Info instance.
 	   *
-	   * @return String description
+	   * @return a short description of the application
 	   **/
 
 	String getDescription();
 
 	/**
-	   * sets this Info's description property to the given description.
+	   * Sets this Info instance's description for the application to the given description.
 	   *
-	   * @param String description
+	   * @param description a short description for the application
 	   */
 	void setDescription(String description);
 
 	/**
-	   * sets this Info's description property to the given description and
-	   * returns this instance of Info
+	   * Sets this Info instance's description for the application to the given description and
+	   * returns this instance of Info.
 	   *
-	   * @param String description
-	   * @return Info
+	   * @param description
+	   * @return this Info instance
 	   */
 	Info description(String description);
 
 	/**
-	   * returns the termsOfService property from a Info instance.
+	   * Returns the URL to the Terms of Service for the API for this instance of Info.
 	   *
-	   * @return String termsOfService
+	   * @return a URL to the Terms of Service for the API
 	   **/
 
 	String getTermsOfService();
 
 	/**
-	   * sets this Info's termsOfService property to the given termsOfService.
+	   * Sets this Info instance's URL to the Terms of Service for the API to the given String.
+	   * The URL must be in the format of a URL.
 	   *
-	   * @param String termsOfService
+	   * @param termsOfService the URL to the Terms of Service for the API
 	   */
 	void setTermsOfService(String termsOfService);
 
 	/**
-	   * sets this Info's termsOfService property to the given termsOfService and
-	   * returns this instance of Info
+	   * Sets this Info instance's URL to the Terms of Service for the API to the given String and
+	   * returns this instance of Info. The URL must be in the format of a URL.
 	   *
-	   * @param String termsOfService
-	   * @return Info
+	   * @param termsOfService the URL to the Terms of Service for the API
+	   * @return this Info instance
 	   */
 	Info termsOfService(String termsOfService);
 
 	/**
-	   * returns the contact property from a Info instance.
+	   * Returns the contact information for the exposed API from this Info instance.
 	   *
-	   * @return Contact contact
+	   * @return the contact information for the exposed API
 	   **/
 
 	Contact getContact();
 
 	/**
-	   * sets this Info's contact property to the given contact.
+	   * Sets this Info instance's contact information for the exposed API.
 	   *
-	   * @param Contact contact
+	   * @param contact the contact information for the exposed API
 	   */
 	void setContact(Contact contact);
 
 	/**
-	   * sets this Info's contact property to the given contact and
-	   * returns this instance of Info
+	   * Sets this Info instance's contact information for the exposed API and
+	   * returns this instance of Info.
 	   *
-	   * @param Contact contact
-	   * @return Info
+	   * @param contact the contact information for the exposed API
+	   * @return this Info instance
 	   */
 	Info contact(Contact contact);
 
 	/**
-	   * returns the license property from a Info instance.
+	   * Returns the license information for the exposed API from this Info instance.
 	   *
-	   * @return License license
+	   * @return the license information for the exposed API
 	   **/
 
 	License getLicense();
 
 	/**
-	   * sets this Info's license property to the given license.
+	   * Sets this Info's license information for the exposed API.
 	   *
-	   * @param License license
+	   * @param license the license information for the exposed API
 	   */
 	void setLicense(License license);
 
 	/**
-	   * sets this Info's license property to the given license and
-	   * returns this instance of Info
+	   * Sets this Info's license information for the exposed API and
+	   * returns this instance of Info.
 	   *
-	   * @param License license
-	   * @return Info
+	   * @param license the license information for the exposed API
+	   * @return this Info instance
 	   */
 	Info license(License license);
 
 	/**
-	   * returns the version property from a Info instance.
+	   * Returns the version of the OpenAPI document for this Info instance.
 	   *
-	   * @return String version
+	   * @return the version of the OpenAPI document
 	   **/
 
 	String getVersion();
 
 	/**
-	   * sets this Info's version property to the given version.
+	   * Sets the version of the OpenAPI document for this instance of Info to the given version.
 	   *
-	   * @param String version
+	   * @param version the version of the OpenAPI document
 	   */
 	void setVersion(String version);
 
 	/**
-	   * sets this Info's version property to the given version and
+	   * Sets the version of the OpenAPI document for this instance of Info to the given version and
 	   * returns this instance of Info
 	   *
-	   * @param String version
-	   * @return Info
+	   * @param version the version of the OpenAPI document
+	   * @return this Info instance
 	   */
 	Info version(String version);
 

From 55b8256212a98217038167b0f421d821fbfd96fb Mon Sep 17 00:00:00 2001
From: janamanoharan <jana.manoharan96@gmail.com>
Date: Tue, 24 Oct 2017 12:12:29 -0400
Subject: [PATCH 07/23] added License docs

Signed-off-by: janamanoharan <jana.manoharan96@gmail.com>
---
 .../openapi/models/info/License.java          | 34 +++++++++----------
 1 file changed, 17 insertions(+), 17 deletions(-)

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 b86ad8d00..92bae0ace 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
@@ -21,57 +21,57 @@
 import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
- * License
+ * This interface represents the License information for the exposed API.
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#licenseObject"
  */
 public interface License extends Constructible, Extensible {
 
 	/**
-	   * returns the name property from a License instance.
+	   * Returns the license name for this License instance that is used for the API.
 	   *
-	   * @return String name
+	   * @return the license name used for the API
 	   **/
 
 	String getName();
 
 	/**
-	   * sets this License's name property to the given name.
+	   * Sets the license name for this License instance that is used for the API.
 	   *
-	   * @param String name
+	   * @param name the license name used for the API
 	   */
 	void setName(String name);
 
 	/**
-	   * sets this License's name property to the given name and
-	   * returns this instance of License
+	   * Sets this License instance's name used for the API and
+	   * returns this instance of License.
 	   *
-	   * @param String name
-	   * @return License
+	   * @param name the license name used for the API
+	   * @return this License instance
 	   */
 	License name(String name);
 
 	/**
-	   * returns the url property from a License instance.
+	   * Returns the URL for this License instance that is used for the API.
 	   *
-	   * @return String url
+	   * @return the URL to the license used for the API
 	   **/
 
 	String getUrl();
 
 	/**
-	   * sets this License's url property to the given url.
+	   * Sets this URL for this License instance that is used for the API.
 	   *
-	   * @param String url
+	   * @param url the URL to the license used for the API
 	   */
 	void setUrl(String url);
 
 	/**
-	   * sets this License's url property to the given url and
-	   * returns this instance of License
+	   * Sets this License instance's URL used for the API and
+	   * returns this instance of License.
 	   *
-	   * @param String url
-	   * @return License
+	   * @param url the URL to the license used for the API
+	   * @return this License instance
 	   */
 	License url(String url);
 

From ef756201187f70d96b0bc914506ae0d80c69ffd1 Mon Sep 17 00:00:00 2001
From: Anna Safonov <anna.safonov@ibm.com>
Date: Tue, 24 Oct 2017 12:14:51 -0400
Subject: [PATCH 08/23] Updated models javadocs and changed  to ref

Signed-off-by: Anna Safonov <anna.safonov@ibm.com>
---
 .../openapi/annotations/media/Encoding.java   |  18 +-
 .../security/SecurityRequirement.java         |   3 +-
 .../annotations/security/SecurityScheme.java  |  26 +-
 .../openapi/models/media/Encoding.java        | 117 ++++++---
 .../models/security/SecurityRequirement.java  |  10 +-
 .../models/security/SecurityScheme.java       | 232 ++++++++++++------
 6 files changed, 274 insertions(+), 132 deletions(-)

diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Encoding.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Encoding.java
index 87bc84f0c..c8cf464da 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Encoding.java
+++ b/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 {};
 
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirement.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirement.java
index a2f90203a..4a9454dc8 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirement.java
+++ b/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 {};
 }
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityScheme.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityScheme.java
index 171afd7d4..2c8b0fcad 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityScheme.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityScheme.java
@@ -25,7 +25,8 @@
 
 
 /**
- * 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 })
@@ -33,6 +34,8 @@
 @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 "";
 
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 123750da0..d023acc6c 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
@@ -49,117 +49,166 @@ public String toString() {
 	}
 
 	/**
-	 * sets this Encoding's contentType property to the given contentType and
-	 * returns this instance of Encoding
-	 *
+	 * 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.
+	 * <p>
+	 * This method sets contentType property for the Encoding instance to the passed parameter
+	 * and returns the modified instance
+	 * <p>
 	 * @param String contentType
 	 * @return Encoding
 	 */
 	Encoding contentType(String contentType);
 
 	/**
-	 * returns the contentType property from a Encoding instance.
-	 *
+	 * 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.
+	 * <p>
+	 * This method returns the contentType property from an Encoding instance.
+	 * <p>
 	 * @return String contentType
 	 **/
 	String getContentType();
 
 	/**
-	 * sets this Encoding's contentType property to the given contentType.
-	 *
+	 * 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.
+	 * <p>
+	 * This method sets thecontentType property of an Encoding instance to the passed contentType parameter.
+	 * <p>
 	 * @param String contentType
 	 */
 	void setContentType(String contentType);
 
 	/**
-	 * sets this Encoding's headers property to the given headers and
-	 * returns this instance of Encoding
-	 *
+	 * Headers property of an Encoding is a map that allows additional information to be provided as headers
+	 * <p>
+	 * This method sets the headers property of Encoding instance to the passed headers argument and
+	 * returns the modified instance.
+	 * <p>
 	 * @param Map&lt;String, Header&gt; headers
 	 * @return Encoding
 	 */
 	Encoding headers(Map<String, Header> headers);
 
 	/**
-	 * returns the headers property from a Encoding instance.
-	 *
+	 * Headers property of an Encoding is a map that allows additional information to be provided as headers
+	 * <p>
+	 * This method returns the headers property from a Encoding instance.
+	 * <p>
 	 * @return Map&lt;String, Header&gt; headers
 	 **/
 	Map<String, Header> getHeaders();
 
 	/**
-	 * sets this Encoding's headers property to the given headers.
-	 *
+	 * Headers property of an Encoding is a map that allows additional information to be provided as headers
+	 * <p>
+	 * This method sets the headers property of Encoding instance to the passed headers argument.
+	 * <p>
 	 * @param Map&lt;String, Header&gt; headers
 	 */
 	void setHeaders(Map<String, Header> headers);
 
 	/**
-	 * sets this Encoding's style property to the given style and
-	 * returns this instance of Encoding
-	 *
+	 * Style describes how the encoding value will be serialized depending on the type of the parameter value.
+	 * <p>
+	 * This method sets the style property of Encoding instance to the passed style argument and
+	 * returns the modified instance
+	 * <p>
 	 * @param String style
 	 * @return Encoding
 	 */
 	Encoding style(String style);
 
 	/**
-	 * returns the style property from a Encoding instance.
-	 *
+	 * Style describes how the encoding value will be serialized depending on the type of the parameter value.
+	 * <p>
+	 * This method returns the style property from a Encoding instance.
+	 * <p>
 	 * @return String style
+	 * @see Parameter for more details on style property
 	 **/
 	String getStyle();
 
 	/**
-	 * sets this Encoding's style property to the given style.
-	 *
+	 * Style describes how the encoding value will be serialized depending on the type of the parameter value.
+	 * <p>
+	 * This method sets the style property of Encoding instance to the given style argument.
+	 * <p>
 	 * @param String style
 	 */
 	void setStyle(String style);
 
 	/**
-	 * sets this Encoding's explode property to the given explode and
-	 * returns this instance of Encoding
-	 *
+	 * 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.
+	 * <p>
+	 * This method sets the explode property of Encoding instance to the given explode argument and
+	 * returns the instance.
+	 * <p>
 	 * @param Boolean explode
 	 * @return Encoding
 	 */
 	Encoding explode(Boolean explode);
 
 	/**
-	 * returns the explode property from a Encoding instance.
-	 *
+	 * 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.
+	 * <p>
+	 * This method returns the explode property from a Encoding instance.
+	 * <p>
 	 * @return Boolean explode
 	 **/
 	Boolean getExplode();
 
 	/**
-	 * sets this Encoding's explode property to the given explode.
-	 *
+	 * 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.
+	 * <p>
+	 * This method sets the explode property of Encoding instance to the given explode argument.
+	 * <p>
 	 * @param Boolean explode
 	 */
 	void setExplode(Boolean explode);
 
 	/**
-	 * sets this Encoding's allowReserved property to the given allowReserved and
-	 * returns this instance of Encoding
-	 *
+	 * AllowReserved determines whether the parameter value SHOULD allow reserved characters to be encoded without percent-encoding.
+	 * <p>
+	 * This method sets the allowReserved property of Encoding instance to the given allowReserved argument and
+	 * returns the instance.
+	 * <p>
 	 * @param Boolean allowReserved
 	 * @return Encoding
+	 * @see RFC3986 for full definition of reserved characters
 	 */
 	Encoding allowReserved(Boolean allowReserved);
 
 	/**
-	 * returns the allowReserved property from a Encoding instance.
-	 *
+	 * AllowReserved determines whether the parameter value SHOULD allow reserved characters to be encoded without percent-encoding.
+	 * <p>
+	 * This method returns the allowReserved property from a Encoding instance.
+	 * <p>
 	 * @return Boolean allowReserved
+	 * @see RFC3986 for full definition of reserved characters
 	 **/
 	Boolean getAllowReserved();
 
 	/**
-	 * sets this Encoding's allowReserved property to the given allowReserved.
+	 * AllowReserved determines whether the parameter value SHOULD allow reserved characters to be encoded without percent-encoding.
+	 * <p>
+	 * This method sets the allowReserved property to the given allowReserved argument.
 	 *
 	 * @param Boolean allowReserved
+	 * @see RFC3986 for full definition of reserved characters
 	 */
 	void setAllowReserved(Boolean allowReserved);
 
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 b67689189..61f25539d 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
@@ -33,11 +33,11 @@ public interface SecurityRequirement extends Constructible, Map<String, List<Str
 	 * Adds a List item to a SecurityRequirement instance
 	 * based on the name and item parameters provided as key-value pair.
 	 * <p>
-	 * Takes value as a String.
+	 * Takes value as a String object.
 	 * 
 	 * @param name
 	 * @param item
-	 * @return Updated SecurityRequirements instance
+	 * @return Updated SecurityRequirement instance
 	 */
 
 	SecurityRequirement addList(String name, String item);
@@ -47,11 +47,11 @@ public interface SecurityRequirement extends Constructible, Map<String, List<Str
 	 * based on the name and item parameters provided as key-value pair
 	 * to the map.
 	 * <p>
-	 * Takes value as a List of strings.
+	 * Takes value as a List of String objects.
 	 * 
 	 * @param name
 	 * @param item
-	 * @return Updated SecurityRequirements instance
+	 * @return Updated SecurityRequirement instance
 	 */
 
 	SecurityRequirement addList(String name, List<String> item);
@@ -61,7 +61,7 @@ public interface SecurityRequirement extends Constructible, Map<String, List<Str
 	 * based on the name parameter provided as key to the map.
 	 * 
 	 * @param name
-	 * @return Updated SecurityRequirements instance
+	 * @return Updated SecurityRequirement instance
 	 */
 
 	SecurityRequirement addList(String name);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java
index ef917309a..5bc7d7550 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java
@@ -28,7 +28,10 @@
 public interface SecurityScheme extends Constructible, Extensible {
 
 	/**
-	 * Gets or Sets type
+	 * Type is a REQUIRED property that specifies the type of SecurityScheme instance.
+	 * <p>
+	 * This method is used in getType and setType to get or set the type of SecurityScheme object 
+	 * to one of the valid values. 
 	 */
 	public enum Type {
 	    APIKEY("apiKey"),
@@ -49,7 +52,10 @@ public String toString() {
 	}
 
 	/**
-	 * Gets or Sets in
+	 * In is a REQUIRED property that specifies the location of the API key.
+	 * <p>
+	 * This method is used in getIn and setIn to get or set the in of SecurityScheme object 
+	 * to one of the enum constants listed.
 	 */
 	public enum In {
 	    COOKIE("cookie"),
@@ -69,26 +75,32 @@ public String toString() {
 	}
 
 	/**
-	 * returns the type property from a SecurityScheme instance.
-	 *
+	 * Type is a REQUIRED property that specifies the type of SecurityScheme instance.
+	 * <p>
+	 * This method returns the type property from SecurityScheme instance.
+	 * <p>
 	 * @return Type type
 	 **/
 
 	SecurityScheme.Type getType();
 
 	/**
-	 * Sets the type property of a SecurityScheme instance
-	 * to the parameter
-	 *
+	 * Type is a REQUIRED property that specifies the type of SecurityScheme instance.
+	 * <p>
+	 * This method sets the type property of SecurityScheme instance
+	 * to the given Type argument.
+	 * <p>
 	 * @param type
 	 */
 
 	void setType(SecurityScheme.Type type);
 
 	/**
-	 * Sets the type property of a SecurityScheme instance
-	 * to the parameter and returns the instance.
-	 *
+	 * Type is a REQUIRED property that specifies the type of SecurityScheme instance.
+	 * <p>
+	 * This method sets the type property of SecurityScheme instance
+	 * to the given Type argument and returns the modified instance.
+	 * <p>
 	 * @param type
 	 * @return SecurityScheme instance with the set type property
 	 */
@@ -96,26 +108,31 @@ public String toString() {
 	SecurityScheme type(SecurityScheme.Type type);
 
 	/**
-	 * returns the description property from a SecurityScheme instance.
-	 *
+	 * A short description for security schema.
+	 * <p>
+	 * This method returns the description property from SecurityScheme instance.
+	 * <p>
 	 * @return String description
 	 **/
 
 	String getDescription();
 
 	/**
-	 * Sets the description property of a SecurityScheme instance
-	 * to the parameter.
-	 *
+	 * A short description for security schema.
+	 * <p>
+	 * This method sets the description property of SecurityScheme instance.
+	 * <p>
 	 * @param description
 	 */
 
 	void setDescription(String description);
 
 	/**
-	 * Sets the description property of a SecurityScheme instance
-	 * to the parameter and returns the instance.
-	 *
+	 * A short description for security schema.
+	 * <p>
+	 * This method sets the description property of SecurityScheme instance
+	 * and returns the modified instance.
+	 * <p>
 	 * @param description
 	 * @return SecurityScheme instance with the set description property
 	 */
@@ -123,26 +140,32 @@ public String toString() {
 	SecurityScheme description(String description);
 
 	/**
-	 * returns the name property from a SecurityScheme instance.
-	 *
+	 * Name is a REQUIRED property - this is the name of the header, query or cookie parameter to be used.
+	 * <p>
+	 * This method returns the name property from SecurityScheme instance.
+	 * <p>
 	 * @return String name
 	 **/
 
 	String getName();
 
 	/**
-	 * Sets the name property of a SecurityScheme instance
+	 * Name is a REQUIRED property - this is the name of the header, query or cookie parameter to be used.
+	 * <p>
+	 * This method sets the name property of SecurityScheme instance
 	 * to the parameter.
-	 *
+	 * <p>
 	 * @param name
 	 */
 
 	void setName(String name);
 
 	/**
-	 * Sets the name property of a SecurityScheme instance
-	 * to the parameter and returns the instance.
-	 *
+	 * Name is a REQUIRED property - this is the name of the header, query or cookie parameter to be used.
+	 * <p>
+	 * This method sets the name property of SecurityScheme instance
+	 * to the given String argument and returns the modified instance.
+	 * <p>
 	 * @param name
 	 * @return SecurityScheme instance with the set name property
 	 */
@@ -150,26 +173,35 @@ public String toString() {
 	SecurityScheme name(String name);
 
 	/**
-	 * returns the in property from a SecurityScheme instance.
-	 *
+	 * In is a REQUIRED property that indicates the location of the API key. 
+	 * Valid values are "query", "header", "cookie".
+	 * <p> 
+	 * This method returns the in property from SecurityScheme instance.
+	 * <p>
 	 * @return In in
 	 **/
 
 	SecurityScheme.In getIn();
 
 	/**
-	 * Sets the in property of a SecurityScheme instance
-	 * to the parameter.
-	 *
+	 * In is a REQUIRED property that indicates the location of the API key. 
+	 * Valid values are "query", "header", "cookie".
+	 * <p>
+	 * The method sets the in property of SecurityScheme instance
+	 * to the given In argument.
+	 * <p>
 	 * @param in
 	 */
 
 	void setIn(SecurityScheme.In in);
 
 	/**
-	 * Sets the in property of a SecurityScheme instance
-	 * to the parameter and returns the instance.
-	 *
+	 * In is a REQUIRED property that indicates the location of the API key. 
+	 * Valid values are "query", "header", "cookie".
+	 * <p>
+	 * This method sets the in property of SecurityScheme instance
+	 * to the given In argument and returns the modified instance.
+	 * <p>
 	 * @param in
 	 * @return SecurityScheme instance with the set in property
 	 */
@@ -177,26 +209,35 @@ public String toString() {
 	SecurityScheme in(SecurityScheme.In in);
 
 	/**
-	 * returns the scheme property from a SecurityScheme instance.
-	 *
+	 * Schema is a REQUIRED property that is the name of the HTTP Authorization scheme
+	 * to be used in the Authorization header as defined in RFC7235.
+	 * <p>
+	 * This method returns the scheme property from SecurityScheme instance.
+	 * <p>
 	 * @return String scheme
 	 **/
 
 	String getScheme();
 
 	/**
-	 * Sets the scheme property of a SecurityScheme instance
-	 * to the parameter.
-	 *
+	 * Schema is a REQUIRED property that is the name of the HTTP Authorization scheme
+	 * to be used in the Authorization header as defined in RFC7235.
+	 * <p>
+	 * This method sets the scheme property of SecurityScheme instance
+	 * to the given String argument.
+	 * <p>
 	 * @param scheme
 	 */
 
 	void setScheme(String scheme);
 
 	/**
-	 * Sets the scheme property of a SecurityScheme instance
-	 * to the parameter and returns the instance.
-	 *
+	 * Schema is a REQUIRED property that is the name of the HTTP Authorization scheme
+	 * to be used in the Authorization header as defined in RFC7235.
+	 * <p>
+	 * This method sets the scheme property of SecurityScheme instance
+	 * to the given String argument and returns the modified instance.
+	 * <p>
 	 * @param scheme
 	 * @return SecurityScheme instance with the set scheme property
 	 */
@@ -204,26 +245,35 @@ public String toString() {
 	SecurityScheme scheme(String scheme);
 
 	/**
-	 * returns the bearerFormat property from a SecurityScheme instance.
-	 *
+	 * bearerFormat is intended as 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.
+	 * <p>
+	 * This method returns the bearerFormat property from SecurityScheme instance.
+	 * <p>
 	 * @return String bearerFormat
 	 **/
 
 	String getBearerFormat();
 
 	/**
-	 * Sets the bearerFormat property of a SecurityScheme instance
-	 * to the parameter.
-	 *
+	 * bearerFormat is intended as 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.
+	 * <p>
+	 * This method sets the bearerFormat property of SecurityScheme instance
+	 * to the given String argument.
+	 * <p>
 	 * @param bearerFormat
 	 */
 
 	void setBearerFormat(String bearerFormat);
 
 	/**
-	 * Sets the bearerFormat property of a SecurityScheme instance
-	 * to the parameter and returns the instance.
-	 *
+	 * bearerFormat is intended as 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.
+	 * <p>
+	 * This method sets the bearerFormat property of SecurityScheme instance to the given String argument
+	 * and returns the modified instance.
+	 * <p>
 	 * @param bearerFormat
 	 * @return SecurityScheme instance with the set bearerFormat property
 	 */
@@ -231,7 +281,11 @@ public String toString() {
 	SecurityScheme bearerFormat(String bearerFormat);
 
 	/**
-	 * returns the flows property from a SecurityScheme instance.
+	 * Flows is a REQUIRED property.
+	 * <p>
+	 * Flows is an object containing configuration information for the flow types supported.
+	 * <p>
+	 * This method returns the flows property from SecurityScheme instance.
 	 *
 	 * @return OAuthFlows flows
 	 **/
@@ -239,18 +293,25 @@ public String toString() {
 	OAuthFlows getFlows();
 
 	/**
-	 * Sets the flows property of a SecurityScheme instance
-	 * to the parameter.
-	 *
+	 * Flows is a REQUIRED property.
+	 * <p>
+	 * Flows is an object containing configuration information for the flow types supported.
+	 * <p>
+	 * This method sets the flows property of SecurityScheme instance
+	 * to the given OAuthFlows argument.
 	 * @param flows
 	 */
 
 	void setFlows(OAuthFlows flows);
 
 	/**
-	 * Sets the flows property of a SecurityScheme instance
-	 * to the parameter and returns the instance.
-	 *
+	 * Flows is a REQUIRED property.
+	 * <p>
+	 * Flows is an object containing configuration information for the flow types supported.
+	 * <p>
+	 * This method sets the flows property of SecurityScheme instance
+	 * to the given OAuthFlows argument and returns the modified instance.
+	 * <p>
 	 * @param flows
 	 * @return SecurityScheme instance with the set flows property
 	 */
@@ -258,7 +319,12 @@ public String toString() {
 	SecurityScheme flows(OAuthFlows flows);
 
 	/**
-	 * returns the openIdConnectUrl property from a SecurityScheme instance.
+	 * openIdConnectUrl is a REQUIRED property.
+	 * <p>
+	 * This property allows to discover OAuth2 configuration values. 
+	 * openIdConnectUrl MUST be in a form of a URL.
+	 * <p>
+	 * This method returns the openIdConnectUrl property from SecurityScheme instance.
 	 *
 	 * @return String openIdConnectUrl
 	 **/
@@ -266,8 +332,13 @@ public String toString() {
 	String getOpenIdConnectUrl();
 
 	/**
-	 * Sets the openIdConnectUrl property of a SecurityScheme instance
-	 * to the parameter.
+	 * openIdConnectUrl is a REQUIRED property.
+	 * <p>
+	 * This property allows to discover OAuth2 configuration values. 
+	 * openIdConnectUrl MUST be in a form of a URL.
+	 * <p>
+	 * This method sets the openIdConnectUrl property of a SecurityScheme instance
+	 * to the given String argument.
 	 *
 	 * @param openIdConnectUrl
 	 */
@@ -275,9 +346,14 @@ public String toString() {
 	void setOpenIdConnectUrl(String openIdConnectUrl);
 
 	/**
-	 * Sets the openIdConnectUrl property of a SecurityScheme instance
-	 * to the parameter and returns the instance.
-	 *
+	 * penIdConnectUrl is a REQUIRED property.
+	 * <p>
+	 * This property allows to discover OAuth2 configuration values. 
+	 * openIdConnectUrl MUST be in a form of a URL.
+	 * <p>
+	 * This method sets the openIdConnectUrl property of SecurityScheme instance
+	 * to the given String argument and returns the modified instance.
+	 * <p>
 	 * @param openIdConnectUrl
 	 * @return SecurityScheme instance with the set openIdConnectUrl property
 	 */
@@ -285,29 +361,35 @@ public String toString() {
 	SecurityScheme openIdConnectUrl(String openIdConnectUrl);
 
 	/**
-	 * returns the $ref property from an SecurityScheme instance.
-	 *
-	 * @return String $ref
+	 * ref property is the reference of the model's location.
+	 * <p>
+	 * This method returns the ref property from SecurityScheme instance.
+	 * <p>
+	 * @return String ref
 	 **/
-	String get$ref();
+	String getRef();
 
 	/**
-	 * Sets the $ref property of a SecurityScheme instance
-	 * to the parameter.
+	 * ref property is the reference of the model's location.
+	 * <p>
+	 * This method sets the ref property of SecurityScheme instance
+	 * to the given String argument.
 	 *
-	 * @param $ref
+	 * @param ref
 	 */
 
-	void set$ref(String $ref);
+	void setRef(String ref);
 
 	/**
-	 * Sets the $ref property of a SecurityScheme instance
-	 * to the parameter and returns the instance.
+	 * ref property is the reference of the model's location.
+	 * <p>
+	 * This method sets the ref property of SecurityScheme instance
+	 * to the given String argument and returns the modified instance.
 	 *
-	 * @param $ref
-	 * @return SecurityScheme instance with the set $ref property
+	 * @param ref
+	 * @return SecurityScheme instance with the set ref property
 	 */
 
-	SecurityScheme $ref(String $ref);
+	SecurityScheme ref(String ref);
 
 }
\ No newline at end of file

From 0891a54bb54a3bf6d9c4452eebf16b152e6190e3 Mon Sep 17 00:00:00 2001
From: Anna Safonov <anna.safonov@ibm.com>
Date: Tue, 24 Oct 2017 16:15:24 -0400
Subject: [PATCH 09/23] Updated javadocs for Scopes, OAuthFlow and OAuthFlows

Signed-off-by: Anna Safonov <anna.safonov@ibm.com>
---
 .../annotations/security/OAuthScope.java      |   1 +
 .../openapi/models/security/OAuthFlow.java    | 120 +++++++++++++-----
 .../openapi/models/security/OAuthFlows.java   |  84 +++++++-----
 .../openapi/models/security/Scopes.java       |  13 +-
 4 files changed, 147 insertions(+), 71 deletions(-)

diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthScope.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthScope.java
index 986e17a4e..a0829a86e 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthScope.java
+++ b/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)
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java
index be0a0c464..9d4d79b04 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java
@@ -21,33 +21,46 @@
 import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
- * OAuthFlow
+ * Configuration details for a supportde OAuthFlow
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#oauthFlowsObject"
  */
 public interface OAuthFlow extends Constructible, Extensible {
 
 	/**
-	 * returns the authorizationUrl property from a OAuthFlow instance.
-	 *
+	 * The authorization URL to be used for this flow. This MUST be in the form of a URL.
+	 * This is a REQUIRED property.
+	 * <p>
+	 * This method returns the authorizationUrl property from OAuthFlow instance.
+	 * <p>
 	 * @return String authorizationUrl
 	 **/
 
 	String getAuthorizationUrl();
 
 	/**
-	 * Sets the authorizationUrl property of an OAuthFlow instance
-	 * to the parameter.
-	 *
+	 * The authorization URL to be used for this flow. This MUST be in the form of a URL.
+	 * This is a REQUIRED property.
+	 * <p>
+	 * Applies to oauth2 ("implicit", "authorizationCode").
+	 * <p>
+	 * This method sets the authorizationUrl property of an OAuthFlow instance
+	 * to the given authorizationUrl argument.
+	 * <p>
 	 * @param authorizationUrl
 	 */
 
 	void setAuthorizationUrl(String authorizationUrl);
 
 	/**
-	 * Sets the authorizationUrl property of an OAuthFlow instance
-	 * to the parameter and returns the instance.
-	 *
+	 * The authorization URL to be used for this flow. This MUST be in the form of a URL.
+	 * This is a REQUIRED property.
+	 * <p>
+	 * Applies to oauth2 ("implicit", "authorizationCode").
+	 * <p>
+	 * This method sets the authorizationUrl property of OAuthFlow instance
+	 * to the given authorizationUrl argument and returns the modified instance.
+	 * <p>
 	 * @param authorizationUrl
 	 * @return OAuthFlow instance with the set authorizationUrl property
 	 */
@@ -55,25 +68,39 @@ public interface OAuthFlow extends Constructible, Extensible {
 	OAuthFlow authorizationUrl(String authorizationUrl);
 
 	/**
-	 * returns the tokenUrl property from a OAuthFlow instance.
-	 *
+	 * The token URL to be used for this flow. This MUST be in the form of a URL.
+	 * This is a REQUIRED property.
+	 * <p>
+	 * This method returns the tokenUrl property from OAuthFlow instance.
+	 * <p>
 	 * @return String tokenUrl
 	 **/
 
 	String getTokenUrl();
 
 	/**
-	 * Sets the tokenUrl property of an OAuthFlow instance.
-	 *
+	 * The token URL to be used for this flow. This MUST be in the form of a URL.
+	 * This is a REQUIRED property.
+	 * <p>
+	 * Applies to oauth2 ("password", "clientCredentials", "authorizationCode").
+	 * <p>
+	 * This method sets the tokenUrl property of OAuthFlow instance 
+	 * to the given tokenUrl argument.
+	 * <p>
 	 * @param tokenkUrl
 	 */
 
 	void setTokenUrl(String tokenUrl);
 
 	/**
-	 * Sets the tokenUrl property of an OAuthFlow instance
-	 * to the parameter and returns the instance.
-	 *
+	 * The token URL to be used for this flow. This MUST be in the form of a URL.
+	 * This is a REQUIRED property.
+	 * <p>
+	 * Applies to oauth2 ("password", "clientCredentials", "authorizationCode").
+	 * <p>
+	 * This method sets the tokenUrl property of OAuthFlow instance 
+	 * to the given tokenUrl argument and returns the instance.
+	 * <p>
 	 * @param tokenUrl
 	 * @return OAuthFlow instance with the set tokenUrl property
 	 */
@@ -81,26 +108,39 @@ public interface OAuthFlow extends Constructible, Extensible {
 	OAuthFlow tokenUrl(String tokenUrl);
 
 	/**
-	 * returns the refreshUrl property from a OAuthFlow instance.
-	 *
+	 * The URL to be used for obtaining refresh tokens. 
+	 * This MUST be in the form of a URL.
+	 * <p>
+	 * This method returns the refreshUrl property from OAuthFlow instance.
+	 * <p>
 	 * @return String refreshUrl
 	 **/
 
 	String getRefreshUrl();
 
 	/**
-	 * Sets the refreshUrl property of an OAuthFlow instance
-	 * to the parameter.
-	 *
+	 * The URL to be used for obtaining refresh tokens. 
+	 * This MUST be in the form of a URL.
+	 * <p>
+	 * Applies to oauth2.
+	 * <p>
+	 * This method sets the refreshUrl property of OAuthFlow instance
+	 * to the given refreshUrl argument.
+	 * <p>
 	 * @param refreshUrl
 	 */
 
 	void setRefreshUrl(String refreshUrl);
 
 	/**
-	 * Sets the refreshUrl property of an OAuthFlow instance
-	 * to the parameter and returns the instance.
-	 *
+	 * The URL to be used for obtaining refresh tokens. 
+	 * This MUST be in the form of a URL.
+	 * <p>
+	 * Applies to oauth2.
+	 * <p>
+	 * This method sets the refreshUrl property of OAuthFlow instance
+	 * to the given refreshUrl argument and returns the modified instance.
+	 * <p>
 	 * @param refreshUrl
 	 * @return OAuthFlow instance with the set refreshUrl property
 	 */
@@ -108,26 +148,42 @@ public interface OAuthFlow extends Constructible, Extensible {
 	OAuthFlow refreshUrl(String refreshUrl);
 
 	/**
-	 * returns the scopes property from a OAuthFlow instance.
-	 *
+	 * The available scopes for the OAuth2 security scheme. 
+	 * A map between the scope name and a short description for it.
+	 * This is a REQUIRED property.
+	 * <p>
+	 * This method returns the scopes property from OAuthFlow instance.
+	 * <p>
 	 * @return Scopes scopes
 	 **/
 
 	Scopes getScopes();
 
 	/**
-	 * Sets the scopes property of an OAuthFlow instance
-	 * to the parameter.
-	 *
+	 * The available scopes for the OAuth2 security scheme. 
+	 * A map between the scope name and a short description for it.
+	 * This is a REQUIRED property.
+	 * <p>
+	 * Applies to oauth2.
+	 * <p>
+	 * This method sets the scopes property of OAuthFlow instance
+	 * to the given argument.
+	 * <p>
 	 * @param scopes
 	 */
 
 	void setScopes(Scopes scopes);
 
 	/**
-	 * Sets the scopes property of an OAuthFlow instance
-	 * to the parameter and returns the instance.
-	 *
+	 * The available scopes for the OAuth2 security scheme. 
+	 * A map between the scope name and a short description for it.
+	 * This is a REQUIRED property.
+	 * <p>
+	 * Applies to oauth2.
+	 * <p>
+	 * This method sets the scopes property of OAuthFlow instance
+	 * to the given argument and returns the modified instance.
+	 * <p>
 	 * @param scopes
 	 * @return OAuthFlow instance with the set scopes property
 	 */
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java
index b270c312d..9c1595007 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java
@@ -21,33 +21,33 @@
 import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
- * OAuthFlows
+ * Configuration of the supported OAuthFlows
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#oauthFlowsObject"
  */
 public interface OAuthFlows extends Constructible, Extensible {
 
 	/**
-	 * returns the implicit property from a OAuthFlows instance.
-	 *
+	 * This method returns the implicit property from OAuthFlows instance.
+	 * <p>
 	 * @return OAuthFlow implicit
 	 **/
 
 	OAuthFlow getImplicit();
 
 	/**
-	 * Sets the implicit property of an OAuthFlows instance
-	 * to parameter.
-	 *
+	 * This method sets the implicit property of OAuthFlows instance
+	 * to the given implicit argument.
+	 * <p>
 	 * @param implicit
 	 */
 
 	void setImplicit(OAuthFlow implicit);
 
 	/**
-	 * Sets the implicit property of an OAuthFlows instance
-	 * to parameter and returns the instance.
-	 *
+	 * This method sets the implicit property of OAuthFlows instance
+	 * to the given implicit argument and returns the modified instance.
+	 * <p>
 	 * @param implicit
 	 * @return OAuthFlows instance with the set implicit property
 	 */
@@ -55,26 +55,32 @@ public interface OAuthFlows extends Constructible, Extensible {
 	OAuthFlows implicit(OAuthFlow implicit);
 
 	/**
-	 * returns the password property from a OAuthFlows instance.
-	 *
+	 * OAuth Resource Owner Password flow
+	 * <p>
+	 * This method returns the password property from OAuthFlows instance.
+	 * <p>
 	 * @return OAuthFlow password
 	 **/
 
 	OAuthFlow getPassword();
 
 	/**
-	 * Sets the password property of an OAuthFlows instance
-	 * to parameter.
-	 *
+	 * OAuth Resource Owner Password flow
+	 * <p>
+	 * This method sets the password property of OAuthFlows instance
+	 * to the given password argument.
+	 * <p>
 	 * @param password
 	 */
 
 	void setPassword(OAuthFlow password);
 
 	/**
-	 * Sets the password property of an OAuthFlows instance
-	 * to parameter and returns the instance.
-	 *
+	 * OAuth Resource Owner Password flow
+	 * <p>
+	 * This method sets the password property of an OAuthFlows instance
+	 * to the given password argument and returns the modified instance.
+	 * <p>
 	 * @param password
 	 * @return OAuthFlows instance with the set password property
 	 */
@@ -82,26 +88,32 @@ public interface OAuthFlows extends Constructible, Extensible {
 	OAuthFlows password(OAuthFlow password);
 
 	/**
-	 * returns the clientCredentials property from a OAuthFlows instance.
-	 *
+	 * OAuth Client Credential flow; previously called application in OpenAPI 2.0
+	 * <p>
+	 * This method returns the clientCredentials property from OAuthFlows instance.
+	 * <p>
 	 * @return OAuthFlow clientCredentials
 	 **/
 
 	OAuthFlow getClientCredentials();
 
 	/**
-	 * Sets the clientCredentials property of an OAuthFlows instance
-	 * to parameter.
-	 *
+	 * OAuth Client Credential flow; previously called application in OpenAPI 2.0
+	 * <p>
+	 * This method sets the clientCredentials property of OAuthFlows instance
+	 * to the given clientCredentials argument.
+	 * <p>
 	 * @param clientCredentials
 	 */
 
 	void setClientCredentials(OAuthFlow clientCredentials);
 
 	/**
-	 * Sets the clientCredentials property of an OAuthFlows instance
-	 * to parameter and returns the instance.
-	 *
+	 * OAuth Client Credential flow; previously called application in OpenAPI 2.0
+	 * <p>
+	 * This method sets the clientCredentials property of OAuthFlows instance
+	 * to the given clientCredentials argument and returns the modified instance.
+	 * <p>
 	 * @param clientCredentials
 	 * @return OAuthFlows instance with the set clientCredentials property
 	 */
@@ -109,26 +121,32 @@ public interface OAuthFlows extends Constructible, Extensible {
 	OAuthFlows clientCredentials(OAuthFlow clientCredentials);
 
 	/**
-	 * returns the authorizationCode property from a OAuthFlows instance.
-	 *
+	 * OAuth Authorization Code flow; previously called accessCode in OpenAPI 2.0
+	 * <p>
+	 * This method returns the authorizationCode property from OAuthFlows instance.
+	 * <p>
 	 * @return OAuthFlow authorizationCode
 	 **/
 
 	OAuthFlow getAuthorizationCode();
 
 	/**
-	 * Sets the authorizationCode property of an OAuthFlows instance
-	 * to parameter.
-	 *
+	 * OAuth Authorization Code flow; previously called accessCode in OpenAPI 2.0
+	 * <p>
+	 * This method sets the authorizationCode property of OAuthFlows instance
+	 * to the given authorizationCode argument.
+	 * <p>
 	 * @param authorizationCode
 	 */
 
 	void setAuthorizationCode(OAuthFlow authorizationCode);
 
 	/**
-	 * Sets the authorizationCode property of an OAuthFlows instance
-	 * to parameter and returns the instance.
-	 *
+	 * OAuth Authorization Code flow; previously called accessCode in OpenAPI 2.0
+	 * <p>
+	 * This method sets the authorizationCode property of OAuthFlows instance
+	 * to the given authorizationCode argument and returns the modified instance.
+	 * <p>
 	 * @param authorizationCode
 	 * @return OAuthFlows instance with the set authorizationCode property
 	 */
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 dea0f53b6..df4b99348 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
@@ -23,15 +23,16 @@
 import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
- * Scopes
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#scopedObject"
- */
+ * Scopes is a property of OAuth Flow Object.
+ * <p>
+ * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#oauthFlowsObject" 
+ **/
+
 public interface Scopes extends Constructible, Extensible, Map<String, String> {
 
 	/**
-	 * Adds name and item parameters to a Scopes instance
-	 * as a key-value
+	 * Adds name of an existing scope object and item parameters to a Scopes instance
+	 * as a key-value pair in a map.
 	 *
 	 * @param name
 	 * @param item

From 2bfc4a201ec1247857033ef585ab728d92695b55 Mon Sep 17 00:00:00 2001
From: Arthur De Magalhaes <ademagalhaes@gmail.com>
Date: Tue, 24 Oct 2017 20:06:52 -0400
Subject: [PATCH 10/23] Updating doc

Signed-off-by: Arthur De Magalhaes <ademagalhaes@gmail.com>
---
 README.adoc | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/README.adoc b/README.adoc
index e56462e2a..10efe27b6 100644
--- a/README.adoc
+++ b/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.

From d0b8a4159201e86fd7d85568460c3c625b61653d Mon Sep 17 00:00:00 2001
From: janamanoharan <jana.manoharan96@gmail.com>
Date: Thu, 26 Oct 2017 14:03:46 -0400
Subject: [PATCH 11/23] added docs for responses and RequestBody. Fixed a few
 things in Info and License

Signed-off-by: janamanoharan <jana.manoharan96@gmail.com>
---
 .../openapi/models/info/Info.java             |   2 +-
 .../openapi/models/info/License.java          |   1 -
 .../models/parameters/RequestBody.java        |  72 ++++++-----
 .../openapi/models/responses/ApiResponse.java | 114 +++++++++---------
 .../models/responses/ApiResponses.java        |  22 ++--
 5 files changed, 103 insertions(+), 108 deletions(-)

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 477cf9d64..272201074 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
@@ -71,7 +71,7 @@ public interface Info extends Constructible, Extensible {
 	   * Sets this Info instance's description for the application to the given description and
 	   * returns this instance of Info.
 	   *
-	   * @param description
+	   * @param description a short description for the application
 	   * @return this Info instance
 	   */
 	Info description(String description);
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 92bae0ace..8e07a74c7 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
@@ -32,7 +32,6 @@ public interface License extends Constructible, Extensible {
 	   *
 	   * @return the license name used for the API
 	   **/
-
 	String getName();
 
 	/**
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java
index 93df4a6c6..207820181 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java
@@ -22,59 +22,60 @@
 import org.eclipse.microprofile.openapi.models.media.Content;
 
 /**
- * RequestBody
+ * This interface represents the request body of an operation in which body parameters can be specified.
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#requestBodyObject"
  */
 public interface RequestBody extends Constructible, Extensible {
 
 	/**
-	 * returns the description property from a RequestBody instance.
+	 * Returns the description of this instance of RequestBody.
 	 *
-	 * @return String description
+	 * @return a brief description of the RequestBody
 	 **/
 
 	String getDescription();
 
 	/**
-	 * Sets the description property of a RequestBody instance
+	 * Sets the description of this instance of RequestBody.
 	 * to the parameter.
 	 *
-	 * @param description
+	 * @param description the brief description of the RequestBody
 	 */
 
 	void setDescription(String description);
 
 	/**
-	 * Sets the description property of a RequestBody instance
-	 * to the parameter and returns the instance.
+	 * Sets the description of this RequestBody and return this instance
+	 * of RequestBody
 	 *
-	 * @param description
-	 * @return RequestBody instance with the modified description property
+	 * @param description the brief description of the RequestBody
+	 * @return this RequestBody instance
 	 */
 
 	RequestBody description(String description);
 
 	/**
-	 * returns the content property from a RequestBody instance.
+	 * Returns the content of this instance of RequestBody, where the keys in content are media type names
+	 * and the values describe it.
 	 *
-	 * @return Content content
+	 * @return the content of this RequestBody
 	 **/
 
 	Content getContent();
 
 	/**
-	 * Sets the content property of a RequestBody instance
-	 * to the parameter.
+	 * Sets the content of this instance of RequestBody, where the keys in content are media type names
+	 * and the values describe it.
 	 *
-	 * @param content
+	 * @param content the content that describes the RequestBody
 	 */
 
 	void setContent(Content content);
 
 	/**
-	 * Sets the content property of a RequestBody instance
-	 * to the parameter and returns the instance.
+	 * Sets the content of this instance of RequestBody, where the keys in content are media type names
+	 * and the values describe it.
 	 *
 	 * @param content
 	 * @return RequestBody instance with the modified content property
@@ -83,57 +84,54 @@ public interface RequestBody extends Constructible, Extensible {
 	RequestBody content(Content content);
 
 	/**
-	 * returns the required property from a RequestBody instance.
+	 * Returns whether this instance of RequestBody is required for the operation.
 	 *
-	 * @return Boolean required
+	 * @return true iff the RequestBody is required, false otherwise
 	 **/
 
 	Boolean getRequired();
 
 	/**
-	 * Sets the required property of a RequestBody instance
-	 * to the parameter.
+	 * Sets whether this instance of RequestBody is required or not.
 	 *
-	 * @param required
+	 * @param required true iff the RequestBody is required, false otherwise
 	 */
 
 	void setRequired(Boolean required);
 
 	/**
-	 * Sets the required property of a RequestBody instance
-	 * to the parameter and returns the instance.
+	 * Sets whether this instance of RequestBody is required or not and returns this instance of RequestBody
 	 *
-	 * @param required
-	 * @return RequestBody instance with the modified required property
+	 * @param required true iff the RequestBody is required, false otherwise
+	 * @return this RequestBody instance
 	 */
 
 	RequestBody required(Boolean required);
 
 	/**
-	 * returns the $ref property from a RequestBody instance.
+	 * Returns the reference to this RequestBody instance that is defined.
 	 *
-	 * @return String $ref
+	 * @return the reference to the response
 	 **/
 
-	String get$ref();
+	String getRef();
 
 	/**
-	 * Sets $ref property of a RequestBody instance
-	 * to the parameter.
+	 * Sets the reference to this RequestBody instance that is defined.
 	 *
-	 * @param $ref
+	 * @param ref the reference to the response
 	 */
 
-	void set$ref(String $ref);
+	void setRef(String ref);
 
 	/**
-	 * Sets $ref property of a RequestBody instance
-	 * to the parameter and return the instance.
+	 * Sets the reference to this RequestBody instance that is defined
+	 * and returns this instance of RequestBody.
 	 *
-	 * @param $ref
-	 * @return RequestBody instance with the set $ref property.
+	 * @param ref the reference to the response
+	 * @return this RequestBody instance
 	 */
 
-	RequestBody $ref(String $ref);
+	RequestBody ref(String ref);
 
 }
\ No newline at end of file
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 5a4f7f8d9..c2e9ec3bb 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
@@ -26,160 +26,156 @@
 import org.eclipse.microprofile.openapi.models.media.Content;
 
 /**
- * ApiResponse
+ * This interface represents a single response from an API Operation, including design-time,
+ * static links to operations based on the response.
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#responseObject"
  */
 public interface ApiResponse extends Constructible, Extensible {
 
 	/**
-	 * returns the description property from a ApiResponse instance.
+	 * Returns a short description of this instance of ApiResponse.
 	 *
-	 * @return String description
+	 * @return a short description of the response
 	 **/
 
 	String getDescription();
 
 	/**
-	 * Sets the description property of a ApiResponse instance
-	 * to the parameter.
+	 * Sets the description of this instance of ApiResponse.
 	 *
-	 * @param description
+	 * @param description a short description of the response
 	 */
 
 	void setDescription(String description);
 
 	/**
-	 * Sets the description property of a ApiResponse instance
-	 * to the parameter and returns the instance.
+	 * Sets the description  of this instance of ApiResponse and returns this ApiResponse
+	 * instance.
 	 *
-	 * @param description
-	 * @return ApiResponse instance with the set description property
+	 * @param description a short description of the response
+	 * @return this ApiResponse instance
 	 */
 
 	ApiResponse description(String description);
 
 	/**
-	 * returns the headers property from a ApiResponse instance.
+	 * Returns the map of Headers in this instance of ApiResponse.
 	 *
-	 * @return Map&lt;String, Header&gt; headers
+	 * @return the headers of this response
 	 **/
 
 	Map<String, Header> getHeaders();
 
 	/**
-	 * Sets the headers property of a ApiResponse instance
-	 * to the parameter.
+	 * Sets the Headers for this instance of ApiResponse with the given map of Headers.
+	 * The Header names are case insensitive and if a Header is defined with the name 'Content-Type',
+	 * then it will be ignored.
 	 *
-	 * @param headers
+	 * @param headers the headers of the response
 	 */
 
 	void setHeaders(Map<String, Header> headers);
 
 	/**
-	 * Sets the headers property of a ApiResponse instance
-	 * to the parameter and returns the instance.
+	 * Sets the Headers for this instance of ApiResponse with the given map of Headers and returns
+	 * this instance of ApiResponse. The Header names are case insensitive and if a Header is defined
+	 * with the name 'Content-Type', then it will be ignored.
 	 *
-	 * @param headers
-	 * @return ApiResponse instance with the set headers property
+	 * @param headers the headers of the response
+	 * @return this ApiResponse instance
 	 */
 
 	ApiResponse headers(Map<String, Header> headers);
 
 	/**
-	 * Adds a header item to the headers map of an ApiResponse instance
-	 * at the specified key and returns the instance.
-	 * If headers is null, creates a new HashMap and adds item to it.
+	 * Adds the given Header to this ApiResponse instance's map of Headers with the given name and
+	 * return this instance of ApiResponse. If this ApiResponse instance does not have any headers, a new map
+	 * is created and the given header is added.
 	 *
-	 * @param name - map key
-	 * @param header - map value
-	 * @return ApiResponse instance with the added header item
+	 * @param name the unique name of the header
+	 * @param header a header for the response
+	 * @return this ApiResponse instance
 	 */
 
 	ApiResponse addHeaderObject(String name, Header header);
 
 	/**
-	 * returns the content property from a ApiResponse instance.
+	 * Returns the map containing descriptions of potential response payload for this instance of ApiResponse.
 	 *
-	 * @return Content content
+	 * @return the potential content of the response
 	 **/
 
 	Content getContent();
 
 	/**
-	 * Sets the content property of an ApiResponse instance
-	 * to the parameter.
+	 * Sets the map containing descriptions of potential response payload for this instance of ApiResponse.
 	 *
-	 * @param content
+	 * @param content the potential content of the response
 	 */
 
 	void setContent(Content content);
 
 	/**
-	 * Sets the content property of an ApiResponse instance
-	 * to the parameter and returns the instance.
+	 * Sets the map containing descriptions of potential response payload for this instance of ApiResponse
+	 * and returns this ApiResponse instance.
 	 *
-	 * @param content
-	 * @return ApiResponse instance with the set content property
+	 * @param content the potential content of the response
+	 * @return this ApiResponse instance
 	 */
 
 	ApiResponse content(Content content);
 
 	/**
-	 * returns the links property from a ApiResponse instance.
+	 * Returns the operations links that can be followed from tis instance of ApiResponse.
 	 *
-	 * @return Link links
+	 * @return operation links that can be followed from the response
 	 **/
 
 	Map<String, Link> getLinks();
 
 	/**
-	 * Sets the links property of an ApiResponse instance
-	 * to the parameter.
+	 * Sets the operations links that can be followed from tis instance of ApiResponse.
 	 *
-	 * @param links
+	 * @param links the operation links followed from the response
 	 */
 
 	void setLinks(Map<String, Link> links);
 
 	/**
-	 * Sets the links property of an ApiResponse instance
-	 * using key, value pair and returns the instance.
-	 * <p>
-	 * If links is null, creates a new HashMap and adds the
-	 * key-value pair to it.
+	 * Sets the operations links for this instance of ApiResponse using the given
+	 * name and Link, and returns this ApiResponse instance.
 	 *
-	 * @param link
-	 * @param link
-	 * @return ApiResponse instance with the set links property
+	 * @param name the short name of the link
+	 * @param link the operation link that can be followed from the response
+	 * @return this ApiResponse instance
 	 */
 
 	ApiResponse link(String name, Link link);
 
 	/**
-	 * returns the $ref property from an ApiResponse instance.
+	 * Returns the reference to this ApiResponse instance that is defined.
 	 *
-	 * @return String $ref
+	 * @return the reference to the response
 	 **/
-	String get$ref();
+	String getRef();
 
 	/**
-	 * Sets the $ref property of an ApiResponse instance
-	 * to the parameter.
+	 * Sets the reference to this ApiResponse instance that is defined.
 	 *
-	 * @param String $ref
+	 * @param ref the reference to the response
 	 */
 
-	void set$ref(String $ref);
+	void setRef(String ref);
 
 	/**
-	 * Sets the $ref property of an ApiResponse instance
-	 * to the parameter and returns the instance.
+	 * Sets the reference to this ApiResponse instance that is defined and
+	 * returns this instance of ApiResponse.
 	 *
-	 * @param $ref
-	 * @return ApiResponse instance with the set $ref property
+	 * @param ref the reference to the response
+	 * @return this ApiResponse instance
 	 */
 
-	ApiResponse $ref(String $ref);
+	ApiResponse ref(String ref);
 
 }
\ No newline at end of file
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 f45759f9c..d7590060a 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
@@ -22,7 +22,8 @@
 import org.eclipse.microprofile.openapi.models.Constructible;
 
 /**
- * ApiResponses
+ * This interface represents the container for the expected responses of an operation.
+ * The container maps a HTTP response code to the expected response.
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#responsesObject"
  */
@@ -33,28 +34,29 @@ public interface ApiResponses extends Constructible, Map<String, ApiResponse> {
 	ApiResponses addApiResponse(String name, ApiResponse item);
 
 	/**
-	 * returns the default property from a ApiResponses instance.
+	 * Returns the default documentation of responses other than the ones declared for specific HTTP response codes
+	 * in this instance of ApiResponses.
 	 *
-	 * @return ApiResponse _default
+	 * @return the default documentation of responses
 	 **/
 
 	ApiResponse getDefault();
 
 	/**
-	 * Sets _default property of an ApiResponses instance
-	 * to the parameter.
+	 * Sets the default documentation of responses for this instance of ApiResponses. This will cover all the
+	 * undeclared responses.
 	 *
-	 * @param _default
+	 * @param _default the default documentation of responses
 	 */
 
 	void setDefault(ApiResponse _default);
 
 	/**
-	 * Sets _default property of an ApiResponses instance
-	 * to the parameter and returns the instance.
+	 * Sets the default documentation of responses for this instance of ApiResponses and
+	 * return this instance of ApiResponses. This will cover all the undeclared responses.
 	 *
-	 * @param _default
-	 * @return ApiResponses instance with the set _default property
+	 * @param _default the default documentation of responses
+	 * @return this ApiResponses instance
 	 */
 
 	ApiResponses _default(ApiResponse _default);

From df5a028cf145fb474e5896451f5f6adc30049a17 Mon Sep 17 00:00:00 2001
From: Anna Safonov <anna.safonov@ibm.com>
Date: Thu, 26 Oct 2017 15:12:46 -0400
Subject: [PATCH 12/23] Updated Server, ServerVariable, and ServerVariables;
 changed allowableValues to enumeration in annotations.

Signed-off-by: Anna Safonov <anna.safonov@ibm.com>
---
 .../openapi/annotations/media/Schema.java     |   5 +-
 .../openapi/annotations/servers/Server.java   |   8 +-
 .../annotations/servers/ServerVariable.java   |  12 +-
 .../openapi/models/servers/Server.java        |  85 +++++++++----
 .../models/servers/ServerVariable.java        | 113 +++++++++++-------
 .../models/servers/ServerVariables.java       |   2 +-
 6 files changed, 146 insertions(+), 79 deletions(-)

diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Schema.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Schema.java
index 84937fecf..3c1f18d7c 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Schema.java
+++ b/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.
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Server.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Server.java
index eaeaa5557..111668e1a 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Server.java
+++ b/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 "";
 
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/ServerVariable.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/ServerVariable.java
index f78ad5169..e09049984 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/ServerVariable.java
+++ b/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 "";
 
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 7ffddb42c..998a59023 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
@@ -21,33 +21,52 @@
 import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
- * Server
+ * An object representing a server.
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#serverObject"
  */
 public interface Server extends Constructible, Extensible {
 
 	/**
-	 * returns the url property from a Server instance.
-	 *
+	 * This method returns the url property of Server instance, which is a URL to the target host.
+	 * <p> 
+	 * 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 enclosed in curly brackets.
+	 * <p>
+	 * This is a REQUIRED property.
+	 * <p>
 	 * @return String url
 	 **/
 
 	String getUrl();
 
 	/**
-	 * Sets the url property of a Server instance
-	 * to the parameter.
-	 * 
+	 * This method sets the url property of Server instance
+	 * to the given url argument, representing a URL to the target host.
+	 * <p>
+	 * 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 enclosed in curly brackets.
+	 * <p>
+	 * This is a REQUIRED property.
+	 * <p>
 	 * @param url
 	 */
 
 	void setUrl(String url);
 
 	/**
-	 * Sets the url property of a Server instance
-	 * to the parameter and returns the instance.
-	 * 
+	 * his method sets the url property of Server instance
+	 * to the given url argument, representing a URL to the target host,
+	 * and returns the modified instance.
+	 * <p>
+	 * 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 enclosed in curly brackets.
+	 * <p>
+	 * This is a REQUIRED property.
+	 * <p>
 	 * @param url
 	 * @return Server instance with the set url property.
 	 */
@@ -55,26 +74,33 @@ public interface Server extends Constructible, Extensible {
 	Server url(String url);
 
 	/**
-	 * returns the description property from a Server instance.
-	 *
+	 * This method returns the description property of Server instance.
+	 * The decsription property is an optional string describing the host designated by the URL.
+	 * <p>
 	 * @return String description
 	 **/
 
 	String getDescription();
 
 	/**
-	 * Sets the description property of a Server instance
-	 * to the parameter.
-	 * 
+	 * This method sets the description property of a Server instance
+	 * to the given description parameter.
+	 * <p>
+	 * Description of a server is an optional string describing the host designated by the URL. 
+	 * CommonMark syntax can be used for rich text representation.
+	 * <p>
 	 * @param description
 	 */
 
 	void setDescription(String description);
 
 	/**
-	 * Sets the description property of a Server instance
-	 * to the parameter and returns the instance.
-	 * 
+	 * This method sets the description property of a Server instance
+	 * to the given description parameter and returns the modified instance.
+	 * <p>
+	 * Description of a server is an optional string describing the host designated by the URL. 
+	 * CommonMark syntax can be used for rich text representation.
+	 * <p>
 	 * @param description
 	 * @return Server instance with the set description property.
 	 */
@@ -82,26 +108,35 @@ public interface Server extends Constructible, Extensible {
 	Server description(String description);
 
 	/**
-	 * returns the variables property from a Server instance.
-	 *
+	 * This method returns the variables property of Server instance.
+	 * <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
 	 **/
 
 	ServerVariables getVariables();
 
 	/**
-	 * Sets the variables property of a Server instance
-	 * to the parameter.
-	 * 
+	 * 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
 	 */
 
 	void setVariables(ServerVariables variables);
 
 	/**
-	 * Sets the variables property of a Server instance
-	 * to the parameter and returns the instance.
-	 * 
+	 * 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
 	 * @return Server instance with the set variables property.
 	 */
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java
index 899983ec2..9c9a5f068 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java
@@ -23,99 +23,124 @@
 import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
- * ServerVariable
+ * An object representing a Server Variable for server URL template substitution.
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#serverVariableObject"
  */
 public interface ServerVariable extends Constructible, Extensible {
 
 	/**
-	 * returns the _enum property from a ServerVariable instance.
-	 *
-	 * @return List&lt;String&gt; _enum
+	 * This  method returns the enumeration property of ServerVariable instance.
+	 * <p>
+	 * This property represents an enumeration of string values to be used 
+	 * if the substitution options are from a limited set
+	 * <p>
+	 * @return List&lt;String&gt; enumeration
 	 **/
 
-	List<String> getEnum();
+	List<String> getEnumeration();
 
 	/**
-	 * Sets the _enum property of a ServerVariable instance
-	 * to parameter.
-	 * 
-	 * @param _enum
+	 * This method sets the enumeration property of ServerVariable instance
+	 * to the given enumeration argument.
+	 * <p>
+	 * This property represents an enumeration of string values to be used 
+	 * if the substitution options are from a limited set
+	 * <p>
+	 * @param enumeration
 	 */
 
-	void setEnum(List<String> _enum);
+	void setEnumeration(List<String> enumeration);
 
 	/**
-	 * Sets the _enum property of a ServerVariable instance
-	 * to parameter and returns the instance.
-	 * 
-	 * @param _enum
-	 * @return ServerVariable instance with the set _enum property
+	 * This method sets the enumeration property of ServerVariable instance
+	 * to the given enumeration argument and returns the modified instance.
+	 * <p>
+	 * This property represents an enum of string values to be used 
+	 * if the substitution options are from a limited set.
+	 * <p>
+	 * @param enumeration
+	 * @return ServerVariable instance with the set enumeration property
 	 */
 
-	ServerVariable _enum(List<String> _enum);
+	ServerVariable enumeration(List<String> enumeration);
 
 	/**
-	 * Adds a string item to _enum list of a ServerVariable instance
+	 * This method adds a string item to enumeration list of a ServerVariable instance
 	 * and returns the instance.
 	 * <p>
-	 * If the _enum list is null, creates a new ArrayList and adds the item.
-	 * 
-	 * @param _enumItem
+	 * If the enumeration list is null, this method should create a new ArrayList and add the item.
+	 * <p>
+	 * @param enumerationItem
 	 * @return ServerVariable instance with the added enum item.
 	 */
 
-	ServerVariable addEnumItem(String _enumItem);
+	ServerVariable addEnumerationItem(String enumerationItem);
 
 	/**
-	 * returns the _default property from a ServerVariable instance.
-	 *
-	 * @return String _default
+	 * The default value to use for substitution, and to send, if an alternate value is not supplied.
+	 * This value MUST be provided by the consumer and is REQUIRED.
+	 * <p>
+	 * This method returns the defaultValue property from ServerVariable instance.
+	 * <p>
+	 * @return String defaultValue
 	 **/
 
-	String getDefault();
+	String getDefaultValue();
 
 	/**
-	 * Sets the _default property of a ServerVariable instance
-	 * to parameter.
-	 * 
-	 * @param _default
+	 * The default value to use for substitution, and to send, if an alternate value is not supplied.
+	 * This value MUST be provided by the consumer and is REQUIRED.
+	 * <p>
+	 * This method sets the defaultValue property of ServerVariable instance
+	 * to the given defaultValue argument.
+	 * <p>
+	 * @param defaultValue
 	 */
 
-	void setDefault(String _default);
+	void setDefaultValue(String defaultValue);
 
 	/**
-	 * Sets the _default property of a ServerVariable instance
-	 * to parameter and returns the instance.
-	 * 
-	 * @param _default
-	 * @return ServerVariable instance with the set _default property
+	 * The default value to use for substitution, and to send, if an alternate value is not supplied.
+	 * This value MUST be provided by the consumer and is REQUIRED.
+	 * <p>
+	 * This method sets the defaultValue property of ServerVariable instance
+	 * to the given defaultValue argument and returns the modified instance.
+	 * <p>
+	 * @param defaultValue
+	 * @return ServerVariable instance with the set defaultValue property
 	 */
 
-	ServerVariable _default(String _default);
+	ServerVariable defaultValue(String defaultValue);
 
 	/**
-	 * returns the description property from a ServerVariable instance.
-	 *
+	 * This method returns the description property of ServerVariable instance.
+	 * Description property is optional for server variable.
+	 * <p>
 	 * @return String description
 	 **/
 
 	String getDescription();
 
 	/**
-	 * Sets the description property of a ServerVariable instance
-	 * to parameter.
-	 * 
+	 * This method sets the description property of ServerVariable instance
+	 * to the given description argument.
+	 * <p>
+	 * Description property is optional for server variable.
+	 * CommonMark syntax can be used for rich text representation.
+	 * <p>
 	 * @param description
 	 */
 
 	void setDescription(String description);
 
 	/**
-	 * Sets the description property of a ServerVariable instance
-	 * to parameter and returns the instance.
-	 * 
+	 * This method sets the description property of ServerVariable instance
+	 * to the given description argument and returns the modeified instance.
+	 * <p>
+	 * Description property is optional for server variable.
+	 * CommonMark syntax can be used for rich text representation.
+	 * <p>
 	 * @param description
 	 * @return ServerVariable instance with the set description property
 	 */
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 82fea423f..93aab58f5 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
@@ -30,7 +30,7 @@
 public interface ServerVariables extends Constructible, Extensible, Map<String, ServerVariable> {
 
 	/**
-	 * Adds a key-value item to a ServerVariables instance from
+	 * This method adds a key-value item to a ServerVariables instance from
 	 * the name-item parameter pair and returns the modified instance.
 	 *
 	 * @param name

From 5cdfe10dd0c58e87a6659746de393f7226441d0f Mon Sep 17 00:00:00 2001
From: Paul Gooderham <turkeyonmarblerye@gmail.com>
Date: Thu, 19 Oct 2017 16:29:30 -0400
Subject: [PATCH 13/23] Update javadoc and check for correctness. 8732

Signed-off-by: Paul Gooderham <turkeyonmarblerye@gmail.com>
---
 .../openapi/models/Components.java            | 308 +++++++++------
 .../openapi/models/ExternalDocumentation.java |  84 ++--
 .../microprofile/openapi/models/OpenAPI.java  | 363 ++++++++++--------
 .../microprofile/openapi/models/PathItem.java | 107 +++++-
 .../microprofile/openapi/models/Paths.java    |  44 ++-
 .../openapi/models/callbacks/Callback.java    |  23 +-
 .../microprofile/openapi/models/tags/Tag.java |  62 ++-
 7 files changed, 635 insertions(+), 356 deletions(-)

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 6f332473d..9bd0b18f1 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
@@ -31,302 +31,380 @@
 
 /**
  * Components
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#componentsObject"
+ * <p>
+ * Holds a set of reusable objects for different aspects of the OAS. All objects
+ * defined within the components object will have no effect on the API unless
+ * they are explicitly referenced from properties outside the components object.
+ * <p>
+ * Fixed Fields
+ * <table border=1>
+ * <tr>
+ * <td>Field Name</td>
+ * <td>Type</td>
+ * <td>Description</td>
+ * </tr>
+ * <tr>
+ * <td>schemas</td>
+ * <td>Map[string, {@link media.Schema Schema} Object | Reference Object]</td>
+ * <td>An object to hold reusable Schema Objects.</td>
+ * </tr>
+ * <tr>
+ * <td>responses</td>
+ * <td>Map[string, {@link responses.ApiResponse Response} Object | Reference
+ * Object]</td>
+ * <td>An object to hold reusable Response Objects.</td>
+ * </tr>
+ * <tr>
+ * <td>parameters</td>
+ * <td>Map[string, {@link parameters.Parameter Parameter} Object | Reference
+ * Object]</td>
+ * <td>An object to hold reusable Parameter Objects.</td>
+ * </tr>
+ * <tr>
+ * <td>examples</td>
+ * <td>Map[string, {@link examples.Example Example} Object | Reference
+ * Object]</td>
+ * <td>An object to hold reusable Example Objects.</td>
+ * </tr>
+ * <tr>
+ * <td>requestBodies</td>
+ * <td>Map[string, {@link parameters.RequestBody Request Body} Object |
+ * Reference Object]</td>
+ * <td>An object to hold reusable Request Body Objects.</td>
+ * </tr>
+ * <tr>
+ * <td>headers</td>
+ * <td>Map[string, {@link headers.Header Header} Object | Reference Object]</td>
+ * <td>An object to hold reusable Header Objects.</td>
+ * </tr>
+ * <tr>
+ * <td>securitySchemes</td>
+ * <td>Map[string, {@link security.SecurityScheme Security Scheme} Object |
+ * Reference Object]</td>
+ * <td>An object to hold reusable Security Scheme Objects.</td>
+ * </tr>
+ * <tr>
+ * <td>links</td>
+ * <td>Map[string, {@link links.Link Link} Object | Reference Object]</td>
+ * <td>An object to hold reusable Link Objects.</td>
+ * </tr>
+ * <tr>
+ * <td>callbacks</td>
+ * <td>Map[string, {@link callbacks.Callback Callback} Object | Reference
+ * Object]</td>
+ * <td>An object to hold reusable Callback Objects.</td>
+ * </tr>
+ * </table>
+ * <p>
+ * All the fixed fields declared above are objects that MUST use keys that match
+ * the regular expression: ^[a-zA-Z0-9\.\-_]+$.
+ * <p>
+ * Field Name Examples:
+ * <ul>
+ * <li>User</li> <li>User_1</li> <li>User_Name</li> <li>user-name</li> <li>my.org.User</li>
+ * </ul>
+ * @see <a href=
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#componentsObject">
+ *      OpenAPI Specification Components Object</a>
  */
 public interface Components extends Constructible, Extensible {
 
 	/**
-	 * returns the schemas property from a Components instance.
+	 * Returns the schemas property from a Components instance.
 	 *
-	 * @return Map&lt;String, Schema&gt; schemas
+	 * @return a Map containing the keys and the reusable schemas for this OpenAPI document
 	 **/
 	Map<String, Schema> getSchemas();
 
 	/**
-	 * sets this Components' schemas property to the given schema.
+	 * Sets this Components' schemas property to the given Map containing keys
+	 * and reusable schema objects.
 	 * 
-	 * @param Map&lt;String, Schema&gt;schemas
+	 * @param schemas a Map containing keys and reusable schema objects
 	 */
 	void setSchemas(Map<String, Schema> schemas);
 
 	/**
-	 * sets this Components' schemas property to the given schema and returns this Components.
+	 * Sets this Components' schemas property to the given Map containing keys
+	 * and reusable schemas.
 	 * 
-	 * @param Map&lt;String, Schema&gt;schemas
-	 * @return Components
+	 * @param schemas a Map containing keys and reusable schemas
+	 * @return the current Components object
 	 */
 	Components schemas(Map<String, Schema> schemas);
 
 	/**
-	 * Adds the given schema to this Components list of schemas, with the given key as its key.
+	 * Adds the given schema to this Components' list of schemas with the given string as its key.
 	 *
-	 * @param String key
-	 * @param Schema schemasItem
-	 * @return Components
+	 * @param key a key conforming to the format required for this object
+	 * @param schemasItem a reusable schema object
+	 * @return the current Components object
 	 */
 	Components addSchemas(String key, Schema schemasItem);
 
 	/**
-	 * returns the responses property from a Components instance.
+	 * Returns the responses property from a Components instance.
 	 *
-	 * @return Map&lt;String, ApiResponse&gt; responses
+	 * @return a Map containing the keys and the reusable responses from API operations for this OpenAPI document
 	 **/
-
 	Map<String, ApiResponse> getResponses();
 
 	/**
-	 * sets this Components' responses property to the given map of ApiResponses.
+	 * Sets this Components' responses property to the given Map containing keys
+	 * and reusable response objects.
 	 *
-	 * @param Map&lt;String, ApiResponse&gt;respones
+	 * @param responses a Map containing keys and reusable response objects
 	 */
 	void setResponses(Map<String, ApiResponse> responses);
 
 	/**
-	 * sets this Components' responses property to the given map of ApiResponses and
-	 * return this instance of Components.
+	 * Sets this Components' responses property to the given Map containing keys
+	 * and reusable response objects.
 	 *
-	 * @param Map&lt;String, ApiResponse&gt;responses
+	 * @param responses a Map containing keys and reusable response objects
+	 * @return the current Components object
 	 */
 	Components responses(Map<String, ApiResponse> responses);
 
 	/**
-	 * Adds the given response to this Components' map of responses, with the given key as its key.
+	 * Adds the given response to this Components' map of responses with the given string as its key.
 	 *
-	 * @param String key
-	 * @param ApiResponse responsesItem
-	 * @return Components instance
+	 * @param key a key conforming to the format required for this object
+	 * @param responsesItem a reusable response object
+	 * @return the current Components object
 	 */
 	Components addResponses(String key, ApiResponse responsesItem);
 
 	/**
-	 * returns the parameters property from a Components instance.
+	 * Returns the parameters property from a Components instance.
 	 *
-	 * @return Map&lt;String, Parameter&gt; parameters
+	 * @return a Map containing the keys and the reusable parameters of API operations for this OpenAPI document
 	 **/
 
 	Map<String, Parameter> getParameters();
 
 	/**
-	 * sets this Components' parameters property to the given map of Parameters.
+	 * Sets this Components' parameters property to the given Map containing keys
+	 * and reusable parameter objects.
 	 *
-	 * @param Map&lt;String, Parameter&gt;parameters
+	 * @param parameters a Map containing keys and reusable parameter objects
 	 */
 	void setParameters(Map<String, Parameter> parameters);
 
 	/**
-	 * sets this Components' parameters property to the given map of Parameters and
-	 * returns this instance of Components.
+	 * Sets this Components' parameters property to the given Map containing keys
+	 * and reusable parameter objects.
 	 *
-	 * @param Map&lt;String, Parameter&gt;parameters
-	 * @return Components
+	 * @param parameters a Map containing keys and reusable parameter objects
+	 * @return the current Components object
 	 */
 	Components parameters(Map<String, Parameter> parameters);
 
 	/**
-	 * Adds the given parameters to this Components' map of parameters, with the given key as its key.
+	 * Adds the given parameter to this Components' map of parameters with the given string as its key.
 	 *
-	 * @param String key
-	 * @param Parameter parametersItem
-	 * @return Components
+	 * @param key a key conforming to the format required for this object
+	 * @param parametersItem a reusable parameter object
+	 * @return the current Components object
 	 */
 	Components addParameters(String key, Parameter parametersItem);
 
 	/**
-	 * returns the examples property from a Components instance.
+	 * Returns the examples property from a Components instance.
 	 *
-	 * @return Map&lt;String, Example&gt; examples
+	 * @return a Map containing the keys and the reusable examples for this OpenAPI document
 	 **/
 
 	Map<String, Example> getExamples();
 
 	/**
-	 * sets this Components' examples property to the given map of Examples.
+	 * Sets this Components' examples property to the given Map containing keys
+	 * and reusable example objects.
 	 *
-	 * @param Map&lt;String, Example&gt;examples
+	 * @param examples a Map containing keys and reusable example objects
 	 */
 	void setExamples(Map<String, Example> examples);
 
 	/**
-	 * sets this Components' examples property to the given map of Examples and
-	 * returns this instance of Components.
+	 * Sets this Components' examples property to the given Map containing keys
+	 * and reusable example objects.
 	 *
-	 * @param Map&lt;String, Example&gt;examples
-	 * @return Components
+	 * @param examples a Map containing keys and reusable example objects
+	 * @return the current Components object
 	 */
 	Components examples(Map<String, Example> examples);
 
 	/**
-	 * Adds the given Example to this Components' map of Examples, with the given key as its key.
+	 * Adds the given example to this Components' map of examples with the given string as its key.
 	 *
-	 * @param String key
-	 * @param Example examplesItem
-	 * @return Components
+	 * @param key a key conforming to the format required for this object
+	 * @param examplesItem a reusable example object
+	 * @return the current Components object
 	 */
 	Components addExamples(String key, Example examplesItem);
 
 	/**
-	 * returns the requestBodies property from a Components instance.
+	 * Returns the requestBodies property from a Components instance.
 	 *
-	 * @return Map&lt;String, RequestBody&gt; requestBodies
+	 * @return a Map containing the keys and the reusable request bodies for this OpenAPI document
 	 **/
-
 	Map<String, RequestBody> getRequestBodies();
 
 	/**
-	 * sets this Components' requestBodies property to the given map of RequestBodies.
+	 * Sets this Components' requestBodies property to the given Map containing keys
+	 * and reusable request body objects.
 	 *
-	 * @param Map&lt;String, RequestBody&gt;requestBodies
-	 */
+	 * @param requestBodies a Map containing the keys and reusable request body objects
+	 **/
 	void setRequestBodies(Map<String, RequestBody> requestBodies);
 
 	/**
-	 * sets this Components' requestBodies property to the given map of RequestBodies and
-	 * returns this instance of Components.
+	 * Sets this Components' requestBodies property to the given Map containing keys
+	 * and reusable request body objects.
 	 *
-	 * @param Map&lt;String, RequestBody&gt;requestBodies
-	 * @return Components
+	 * @param requestBodies a Map containing the keys and reusable request body objects
+	 * @return the current Components object
 	 */
 	Components requestBodies(Map<String, RequestBody> requestBodies);
 
 	/**
-	 * Adds the given RequestBody to this Components' map of RequestBodies, with the given key as its key.
+	 * Adds the given request body to this Components' map of request bodies with the given string as its key.
 	 *
-	 * @param String key
-	 * @param RequestBody requestBodiesItem
-	 * @return Components
+	 * @param key a key conforming to the format required for this object
+	 * @param requestBodiesItem a reusable request body object
+	 * @return the current Components object
 	 */
 	Components addRequestBodies(String key, RequestBody requestBodiesItem);
 
 	/**
-	 * returns the headers property from a Components instance.
+	 * Returns the headers property from a Components instance.
 	 *
-	 * @return Map&lt;String, Header&gt; headers
+	 * @return a Map containing the keys and the reusable headers for this OpenAPI document
 	 **/
-
 	Map<String, Header> getHeaders();
 
 	/**
-	 * sets this Components' headers property to the given map of Headers.
+	 * Sets this Components' headers property to the given Map containing keys
+	 * and reusable header objects.
 	 *
-	 * @param Map&lt;String, Header&gt;headers
+	 * @param headers a Map containing the keys and reusable header objects
 	 */
 	void setHeaders(Map<String, Header> headers);
 
 	/**
-	 * sets this Components' headers property to the given map of Headers and
-	 * returns this instance of Components.
+	 * Sets this Components' headers property to the given Map containing keys
+	 * and reusable header objects.
 	 *
-	 * @param Map&lt;String, Header&gt;headers
-	 * @return Components
+	 * @param headers a Map containing the keys and reusable header objects
+	 * @return the current Components object
 	 */
 	Components headers(Map<String, Header> headers);
 
 	/**
-	 * Adds the given Header to this Components' map of Headers, with the given key as its key.
+	 * Adds the given header to this Components' map of headers with the given string as its key.
 	 *
-	 * @param String key
-	 * @param Header headersItem
-	 * @return Components
+	 * @param key a key conforming to the format required for this object
+	 * @param headersItem a reusable header object
+	 * @return the current Components object
 	 */
 	Components addHeaders(String key, Header headersItem);
 
 	/**
-	 * returns the securitySchemes property from a Components instance.
+	 * Returns the securitySchemes property from a Components instance.
 	 *
-	 * @return Map&lt;String, SecurityScheme&gt; securitySchemes
+	 * @return a Map containing the keys and the reusable security schemes for this OpenAPI document
 	 **/
-
 	Map<String, SecurityScheme> getSecuritySchemes();
 
 	/**
-	 * sets this Components' securitySchemes property to the given map of SecuritySchemes.
+	 * Sets this Components' securitySchemes property to the given Map containing keys
+	 * and reusable security scheme objects.
 	 *
-	 * @param Map&lt;String, SecurityScheme&gt;securitySchemes
+	 * @param securitySchemes a Map containing the keys and reusable security scheme objects
 	 */
 	void setSecuritySchemes(Map<String, SecurityScheme> securitySchemes);
 
 	/**
-	 * sets this Components' securitySchemes property to the given map of SecuritySchemes and
-	 * returns this instance of Components.
+	 * Sets this Components' securitySchemes property to the given Map containing keys
+	 * and reusable security scheme objects.
 	 *
-	 * @param Map&lt;String, SecurityScheme&gt;securitySchemes
-	 * @return Components
+	 * @param securitySchemes a Map containing the keys and reusable security scheme objects
+	 * @return the current Components object
 	 */
 	Components securitySchemes(Map<String, SecurityScheme> securitySchemes);
 
 	/**
-	 * Adds the given SecurityScheme to this Components' map of SecuritySchemes, with the given key as its key.
+	 * Adds the given security scheme to this Components' map of security schemes with the given string as its key.
 	 *
-	 * @param String key
-	 * @param SecurityScheme securitySchemesItem
-	 * @return Components
+	 * @param key a key conforming to the format required for this object
+	 * @param securitySchemesItem a reusable security scheme object
+	 * @return the current Components object
 	 */
 	Components addSecuritySchemes(String key, SecurityScheme securitySchemesItem);
 
 	/**
-	 * returns the links property from a Components instance.
+	 * Returns the links property from a Components instance.
 	 *
-	 * @return Map&lt;String, Link&gt; links
+	 * @return a Map containing the keys and the reusable links for this OpenAPI document
 	 **/
-
 	Map<String, Link> getLinks();
 
 	/**
-	 * sets this Components' links property to the given map of Links.
+	 * Sets this Components' links property to the given Map containing keys
+	 * and reusable link objects.
 	 *
-	 * @param Map&lt;String, Link&gt;links
+	 * @param links a Map containing the keys and reusable link objects
 	 */
 	void setLinks(Map<String, Link> links);
 
 	/**
-	 * sets this Components' links property to the given map of Links and
-	 * returns this instance of Components.
+	 * Sets this Components' links property to the given Map containing keys
+	 * and reusable link objects.
 	 *
-	 * @param Map&lt;String, Link&gt;links
-	 * @return Components
+	 * @param links a Map containing the keys and reusable link objects
+	 * @return the current Components object
 	 */
 	Components links(Map<String, Link> links);
 
 	/**
-	 * Adds the given Link to this Components' map of Links, with the given key as its key.
+	 * Adds the given link to this Components' map of links with the given string as its key.
 	 *
-	 * @param String key
-	 * @param Link linksItem
-	 * @return Components
+	 * @param key a key conforming to the format required for this object
+	 * @param linksItem a reusable link object
+	 * @return the current Components object
 	 */
 	Components addLinks(String key, Link linksItem);
 
 	/**
-	 * returns the callbacks property from a Components instance.
+	 * Returns the callbacks property from a Components instance.
 	 *
-	 * @return Map&lt;String, Callback&gt; callbacks
+	 * @return a Map containing the keys and the reusable callbacks for this OpenAPI document
 	 **/
-
 	Map<String, Callback> getCallbacks();
 
 	/**
-	 * sets this Components' callbacks property to the given map of Callbacks.
+	 * Sets this Components' callbacks property to the given Map containing keys
+	 * and reusable callback objects.
 	 *
-	 * @param Map&lt;String, Callback&gt;callbacks
+	 * @param callbacks a Map containing the keys and reusable callback objects
 	 */
 	void setCallbacks(Map<String, Callback> callbacks);
 
 	/**
-	 * sets this Components' callbacks property to the given map of Callbacks and
-	 * returns this instance of Components.
+	 * Sets this Components' callbacks property to the given Map containing keys
+	 * and reusable callback objects.
 	 *
-	 * @param Map&lt;String, Callback&gt;callbacks
-	 * @return Components
+	 * @param callbacks a Map containing the keys and reusable callback objects
+	 * @return the current Components object
 	 */
 	Components callbacks(Map<String, Callback> callbacks);
 
 	/**
-	 * Adds the given Callback to this Components' map of Callbacks, with the given key as its key.
+	 * Adds the given callback to this Components' map of callbacks with the given string as its key.
 	 *
-	 * @param String key
-	 * @param Callback callbacksItem
-	 * @return Components
+	 * @param key a key conforming to the format required for this object
+	 * @param callbacksItem a reusable callback object
+	 * @return the current Components object
 	 */
 	Components addCallbacks(String key, Callback callbacksItem);
 
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
index 690fc5573..a89fb9482 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
@@ -19,57 +19,77 @@
 
 /**
  * ExternalDocumentation
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#externalDocumentationObject"
+ * <p>
+ * Allows referencing an external resource for extended documentation.
+ * <p>
+ * Fixed Fields
+ * <table border=1>
+ * <tr>
+ * <td>Field Name</td>
+ * <td>Type</td>
+ * <td>Description</td>
+ * </tr>
+ * <tr>
+ * <td>description</td>
+ * <td>String</td>
+ * <td>A short description of the target documentation. CommonMark syntax MAY be
+ * used for rich text representation.</td>
+ * </tr>
+ * <tr>
+ * <td>url</td>
+ * <td>String</td>
+ * <td>REQUIRED. The URL for the target documentation. Value MUST be in the format of a URL.</td>
+ * </tr>
+ * </table>
+ * 
+ * @see <a href=
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#externalDocumentationObject">OpenAPI
+ *      Specification External Documentation Object</a>
  */
 public interface ExternalDocumentation extends Constructible, Extensible {
 
 	/**
-	   * returns the description property from a ExternalDocumentation instance.
-	   *
-	   * @return String description
-	   **/
-
+	  * Returns the description property from an ExternalDocumentation instance.
+	  *
+	  * @return a short description of the target documentation
+	  **/
 	String getDescription();
 
 	/**
-	   * sets this ExternalDocumentation's description property to the given description.
-	   *
-	   * @param String description
-	   */
+	  * Sets this ExternalDocumentation's description property to the given string.
+	  *
+	  * @param description a short description of the target documentation
+	  */
 	void setDescription(String description);
 
 	/**
-	   * sets this ExternalDocumentation's description property to the given description and
-	   * returns this instance of ExternalDocumentation.
-	   *
-	   * @param String description
-	   * @return ExternalDocumentation
-	   */
+	  * Sets this ExternalDocumentation's description property to the given string.
+	  *
+	  * @param description a short description of the target documentation
+	  * @return the current ExternalDocumentation instance
+	  */
 	ExternalDocumentation description(String description);
 
 	/**
-	   * returns the url property from a ExternalDocumentation instance.
-	   *
-	   * @return String url
-	   **/
-
+	  * Returns the url property from an ExternalDocumentation instance.
+	  *
+	  * @return the URL for the target documentation
+	  **/
 	String getUrl();
 
 	/**
-	   * sets this ExternalDocumentation's url property to the given url.
-	   *
-	   * @param String url
-	   */
+	  * Sets this ExternalDocumentation's url property to the given string.
+	  *
+	  * @param url the URL for the target documentation
+	  */
 	void setUrl(String url);
 
 	/**
-	   * sets this ExternalDocumentation's url property to the given url and
-	   * returns this instance of ExternalDocumentation.
-	   *
-	   * @param String url
-	   * @return ExternalDocumentation
-	   */
+	  * Sets this ExternalDocumentation's url property to the given string.
+	  *
+	  * @param url the URL for the target documentation
+	  * @return the current ExternalDocumentation instance
+	  */
 	ExternalDocumentation url(String url);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
index c568cd710..a99a4fea8 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
@@ -28,254 +28,305 @@
 
 /**
  * OpenAPI
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md"
+ * <p>
+ * This is the root document object of the OpenAPI document. It contains the
+ * following required and optional fields.
+ * <table border=1>
+ * <tr>
+ * <td>Field Name</td>
+ * <td>Type</td>
+ * <td>Description</td>
+ * </tr>
+ * <tr>
+ * <td>openapi</td>
+ * <td>String</td>
+ * <td>REQUIRED. This string MUST be the semantic version number of the OpenAPI
+ * Specification version that the OpenAPI document uses. The openapi field
+ * SHOULD be used by tooling specifications and clients to interpret the OpenAPI
+ * document. This is not related to the API info.version string.</td>
+ * </tr>
+ * <tr>
+ * <td>info</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.info.Info Info}</td>
+ * <td>REQUIRED. Provides metadata about the API. The metadata MAY be used by
+ * tooling as required.</td>
+ * </tr>
+ * <tr>
+ * <td>servers</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.servers.Server Server}</td>
+ * <td>An array of Server Objects, which provide connectivity information to a
+ * target server. If the servers property is not provided, or is an empty array,
+ * the default value would be a Server Object with a url value of /.</td>
+ * </tr>
+ * <tr>
+ * <td>paths</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.Paths Paths} Object</td>
+ * <td>REQUIRED. The available paths and operations for the API.</td>
+ * </tr>
+ * <tr>
+ * <td>components</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.Components Components}</td>
+ * <td>An element to hold various schemas for the specification.</td>
+ * </tr>
+ * <tr>
+ * <td>security</td>
+ * <td>{@link
+ * org.eclipse.microprofile.openapi.models.security.SecurityRequirement SecurityRequirement}</td>
+ * <td>A declaration of which security mechanisms can be used across the API.
+ * The list of values includes alternative security requirement objects that can
+ * be used. Only one of the security requirement objects need to be satisfied to
+ * authorize a request. Individual operations can override this definition.</td>
+ * </tr>
+ * <tr>
+ * <td>tags</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.tags.Tag Tag}</td>
+ * <td>A list of tags used by the specification with additional metadata. The
+ * order of the tags can be used to reflect on their order by the parsing tools.
+ * Not all tags that are used by the Operation Object must be declared. The tags
+ * that are not declared MAY be organized randomly or based on the tools' logic.
+ * Each tag name in the list MUST be unique.</td>
+ * </tr>
+ * <tr>
+ * <td>externalDocs</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.ExternalDocumentation ExternalDocumentation}</td>
+ * <td>Additional external documentation.</td>
+ * </tr>
+ * </table>
+ * 
+ * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md">OpenAPI Specification</a>
  */
 public interface OpenAPI extends Constructible, Extensible {
 
 	/**
-	   * returns the openapi property from a OpenAPI instance.
-	   *
-	   * @return String openapi
-	   **/
+	  * Returns the openapi property from an OpenAPI instance.
+	  *
+	  * @return the semantic version number of the OpenAPI Specification version that the OpenAPI document uses
+	  **/
 
 	String getOpenapi();
 
 	/**
-	   * sets this OpenAPI's openapi property to the given openapi.
-	   *
-	   * @param String openapi
-	   */
+	  * Sets this OpenAPI instance's openapi property to the given string.
+	  *
+	  * @param openapi the semantic version number of the OpenAPI Specification version that the OpenAPI document uses
+	  */
 	void setOpenapi(String openapi);
 
 	/**
-	   * sets this OpenAPI's openapi property to the given openapi and
-	   * returns this instance of OpenAPI
-	   *
-	   * @param String openapi
-	   * @return OpenAPI
-	   */
+	  * Sets this OpenAPI instance's openapi property to the given string.
+	  *
+	  * @param openapi the semantic version number of the OpenAPI Specification version that the OpenAPI document uses
+	  * @return the current OpenAPI object
+	  */
 	OpenAPI openapi(String openapi);
 
 	/**
-	   * returns the info property from a OpenAPI instance.
-	   *
-	   * @return Info info
-	   **/
+	  * Returns the info property from an OpenAPI instance.
+	  *
+	  * @return metadata about the API
+	  **/
 
 	Info getInfo();
 
 	/**
-	   * sets this OpenAPI's info property to the given info.
-	   *
-	   * @param Info info
-	   */
+	  * Sets this OpenAPI instance's info property to the given object.
+	  *
+	  * @param info metadata about the API
+	  */
 	void setInfo(Info info);
 
 	/**
-	   * sets this OpenAPI's info property to the given info and
-	   * returns this instance of OpenAPI
-	   *
-	   * @param Info info
-	   * @return OpenAPI
-	   */
+	  * Sets this OpenAPI instance's info property to the given object.
+	  *
+	  * @param info metadata about the API
+	  * @return the current OpenAPI object
+	  */
 	OpenAPI info(Info info);
 
 	/**
-	   * returns the externalDocs property from a OpenAPI instance.
-	   *
-	   * @return ExternalDocumentation externalDocs
-	   **/
+	  * Returns the externalDocs property from an OpenAPI instance.
+	  *
+	  * @return additional external documentation
+	  **/
 	ExternalDocumentation getExternalDocs();
 
 	/**
-	   * sets this OpenAPI's externalDocs property to the given externalDocs.
-	   *
-	   * @param ExternalDocumentation externalDocs
-	   */
+	  * Sets this OpenAPI instance's externalDocs property to the given object.
+	  *
+	  * @param externalDocs additional external documentation.
+	  */
 	void setExternalDocs(ExternalDocumentation externalDocs);
 
 	/**
-	   * sets this OpenAPI's externalDocs property to the given externalDocs and
-	   * returns this instance of OpenAPI
-	   *
-	   * @param ExternalDocumentation externalDocs
-	   * @return OpenAPI
-	   */
+	  * Sets this OpenAPI instance's externalDocs property to the given object.
+	  *
+	  * @param externalDocs additional external documentation
+	  * @return the current OpenAPI object
+	  */
 	OpenAPI externalDocs(ExternalDocumentation externalDocs);
 
 	/**
-	   * returns the Servers defined in the API
-	   *
-	   * @return List&lt;Server&gt; servers
-	   **/
+	  * Returns the Servers defined in the API
+	  *
+	  * @return Server objects which provide connectivity information to target servers
+	  **/
 
 	List<Server> getServers();
 
 	/**
-	   * sets this OpenAPI's servers property to the given servers.
-	   *
-	   * @param List&lt;Server&gt;servers
-	   */
+	  * Sets this OpenAPI instance's servers property to the given servers.
+	  *
+	  * @param servers Server objects which provide connectivity information to target servers
+	  */
 	void setServers(List<Server> servers);
 
 	/**
-	   * sets this OpenAPI's servers property to the given servers and
-	   * returns this instance of OpenAPI
-	   *
-	   * @param List&lt;Server&gt;servers
-	   * @return OpenAPI
-	   */
+	  * Sets this OpenAPI instance's servers property to the given servers.
+	  *
+	  * @param servers Server objects which provide connectivity information to target servers
+	  * @return the current OpenAPI object
+	  */
 	OpenAPI servers(List<Server> servers);
 
 	/**
-	   * Adds the given serversItem to this OpenAPI's list of servers, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param Server serversItem
-	   * @return OpenAPI
-	   */
+	  * Adds the given server to this OpenAPI instance's list of servers.
+	  *
+	  * @param serversItem Server object which provides connectivity information to a target server
+	  * @return the current OpenAPI object
+	  */
 	OpenAPI addServersItem(Server serversItem);
 
 	/**
-	   * returns the security property from a OpenAPI instance.
-	   *
-	   * @return List&lt;SecurityRequirement&gt; security
-	   **/
+	  * Returns the security property from an OpenAPI instance.
+	  *
+	  * @return which security mechanisms can be used across the API
+	  **/
 
 	List<SecurityRequirement> getSecurity();
 
 	/**
-	   * sets this OpenAPI's security property to the given security.
-	   *
-	   * @param List&lt;SecurityRequirement&gt;security
-	   */
+	  * Sets this OpenAPI instance's security property to the given list.
+	  *
+	  * @param security which security mechanisms can be used across the API
+	  */
 	void setSecurity(List<SecurityRequirement> security);
 
 	/**
-	   * sets this OpenAPI's security property to the given security and
-	   * returns this instance of OpenAPI
-	   *
-	   * @param List&lt;SecurityRequirement&gt;servers
-	   * @return OpenAPI
-	   */
+	  * Sets this OpenAPI instance's security property to the given list.
+	  *
+	  * @param security which security mechanisms can be used across the API
+	  * @return the current OpenAPI object
+	  */
 	OpenAPI security(List<SecurityRequirement> security);
 
 	/**
-	   * Adds the given securityItem to this OpenAPI's list of securitItems, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param SecurityRequirement securityItem
-	   * @return OpenAPI
-	   */
+	  * Adds the given security requirement to this OpenAPI instance's list of security requirements.
+	  *
+	  * @param securityItem security mechanism which can be used across the API
+	  * @return the current OpenAPI object
+	  */
 	OpenAPI addSecurityItem(SecurityRequirement securityItem);
 
 	/**
-	   * returns the tags property from a OpenAPI instance.
-	   *
-	   * @return List&lt;Tag&gt; tags
-	   **/
+	  * Returns the tags property from an OpenAPI instance.
+	  *
+	  * @return tags used by the specification
+	  **/
 
 	List<Tag> getTags();
 
 	/**
-	   * sets this OpenAPI's tags property to the given Tags.
-	   *
-	   * @param List&lt;Tag&gt;tags
-	   */
+	  * Sets this OpenAPI instance's tags property to the given Tags.
+	  *
+	  * @param tags tags used by the specification
+	  */
 	void setTags(List<Tag> tags);
 
 	/**
-	   * sets this OpenAPI's tags property to the given tags and
-	   * returns this instance of OpenAPI
-	   *
-	   * @param List&lt;Tag&gt;tags
-	   * @return OpenAPI
-	   */
+	  * Sets this OpenAPI instance's tags property to the given tags.
+	  *
+	  * @param tags tags used by the specification
+	  * @return the current OpenAPI object
+	  */
 	OpenAPI tags(List<Tag> tags);
 
 	/**
-	   * Adds the given tagsItem to this OpenAPI's list of tags, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param Tag tagsItem
-	   * @return OpenAPI
-	   */
+	  * Adds the given tag to this OpenAPI instance's list of tags.
+	  *
+	  * @param tagsItem a tag used by the specification
+	  * @return the current OpenAPI object
+	  */
 	OpenAPI addTagsItem(Tag tagsItem);
 
 	/**
-	   * returns the paths property from a OpenAPI instance.
-	   *
-	   * @return Paths paths
-	   **/
-
+	  * Returns the paths property from an OpenAPI instance.
+	  *
+	  * @return the available paths and operations for the API
+	  **/
 	Paths getPaths();
 
 	/**
-	   * sets this OpenAPI's paths property to the given paths.
-	   *
-	   * @param List&lt;Paths&gt;paths
-	   */
+	  * Sets this OpenAPI instance's paths property to the given paths.
+	  *
+	  * @param paths the available paths and operations for the API
+	  */
 	void setPaths(Paths paths);
 
 	/**
-	   * sets this OpenAPI's paths property to the given paths and
-	   * returns this instance of OpenAPI
-	   *
-	   * @param List&lt;Paths&gt;paths
-	   * @return OpenAPI
-	   */
+	  * Sets this OpenAPI instance's paths property to the given paths.
+	  *
+	  * @param paths the available paths and operations for the API
+	  * @return the current OpenAPI object
+	  */
 	OpenAPI paths(Paths paths);
 
 	/**
-	   * returns the components property from a OpenAPI instance.
-	   *
-	   * @return Components components
-	   **/
+	  * Adds the given path item to this OpenAPI instance's list of paths
+	  * 
+	  * @param name a path name in the format valid for a Paths object
+	  * @param path the path item added to the list of paths
+	  * @return the current OpenAPI object
+	  */
+	OpenAPI path(String name, PathItem path);
 
+	/**
+	  * Returns the components property from an OpenAPI instance.
+	  *
+	  * @return schemas used in the specification
+	  **/
 	Components getComponents();
 
 	/**
-	   * sets this OpenAPI's components property to the given components.
-	   *
-	   * @param List&lt;Components&gt;components
-	   */
+	  * Sets this OpenAPI instance's components property to the given components.
+	  *
+	  * @param components schemas used in the specification
+	  */
 	void setComponents(Components components);
 
 	/**
-	   * sets this OpenAPI's components property to the given components and
-	   * returns this instance of OpenAPI
-	   *
-	   * @param List&lt;Components&gt;components
-	   * @return OpenAPI
-	   */
+	  * Sets this OpenAPI instance's components property to the given components.
+	  *
+	  * @param components schemas used in the specification
+	  * @return the current OpenAPI object
+	  */
 	OpenAPI components(Components components);
 
 	/**
-	   * Adds the given path item to this OpenAPI's list of paths
-	   * 
-	   * @param String name
-	   * @param PathItem path
-	   * @return OpenAPI
-	   */
-	OpenAPI path(String name, PathItem path);
-
-	/**
-	   * Adds the given schema to this OpenAPI's components property.
-	   * 
-	   * @param String name
-	   * @param Schema schema
-	   * @return OpenAPI
-	   */
+	  * Adds the given schema to this OpenAPI instance's components property.
+	  * 
+	  * @param name the canonical name of the given schema
+	  * @param schema a schema to add to the components property
+	  * @return the current OpenAPI object
+	  */
 	OpenAPI schema(String name, Schema schema);
 
 	/**
-	   * Adds the given securityScheme to this OpenAPI's securitySchemes
-	   * 
-	   * @param String name
-	   * @param SecurityScheme securityScheme
-	   * @return OpenAPI
-	   */
-	OpenAPI schemaRequirement(String name, SecurityScheme securityScheme);
-
+	  * Adds the given security scheme to this OpenAPI instance's components property.
+	  * This convenience method is similar to Components.addSecuritySchemes. 
+	  * 
+	  * @param name the canonical name of the given security scheme
+	  * @param securityScheme a security scheme to add to the components property
+	  * @return the current OpenAPI object
+	  */
+	OpenAPI securityScheme(String name, SecurityScheme securityScheme);
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
index b32d911f4..7641e992d 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
@@ -25,8 +25,111 @@
 
 /**
  * PathItem
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#pathItemObject"
+ * <p>
+ * Describes the operations available on a single path. A Path Item MAY be
+ * empty, due to ACL constraints. The path itself is still exposed to the
+ * documentation viewer but they will not know which operations and parameters
+ * are available.
+ * <p>
+ * Fixed Fields
+ * <table border=1>
+ * <tr>
+ * <td>Field Name</td>
+ * <td>Type</td>
+ * <td>Description</td>
+ * </tr>
+ * <tr>
+ * <td>$ref</td>
+ * <td>string</td>
+ * <td>Allows for an external definition of this path item. The referenced
+ * structure MUST be in the format of a Path Item Object. If there are conflicts
+ * between the referenced definition and this Path Item's definition, the
+ * behavior is undefined.</td>
+ * </tr>
+ * <tr>
+ * <td>summary</td>
+ * <td>string</td>
+ * <td>An optional, string summary, intended to apply to all operations in this
+ * path.</td>
+ * </tr>
+ * <tr>
+ * <td>description</td>
+ * <td>string</td>
+ * <td>An optional, string description, intended to apply to all operations in
+ * this path. CommonMark syntax MAY be used for rich text representation.</td>
+ * </tr>
+ * <tr>
+ * <td>get</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
+ * Object</td>
+ * <td>A definition of a GET operation on this path.</td>
+ * </tr>
+ * <tr>
+ * <td>put</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
+ * Object</td>
+ * <td>A definition of a PUT operation on this path.</td>
+ * </tr>
+ * <tr>
+ * <td>post</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
+ * Object</td>
+ * <td>A definition of a POST operation on this path.</td>
+ * </tr>
+ * <tr>
+ * <td>delete</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
+ * Object</td>
+ * <td>A definition of a DELETE operation on this path.</td>
+ * </tr>
+ * <tr>
+ * <td>options</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
+ * Object</td>
+ * <td>A definition of a OPTIONS operation on this path.</td>
+ * </tr>
+ * <tr>
+ * <td>head</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
+ * Object</td>
+ * <td>A definition of a HEAD operation on this path.</td>
+ * </tr>
+ * <tr>
+ * <td>patch</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
+ * Object</td>
+ * <td>A definition of a PATCH operation on this path.</td>
+ * </tr>
+ * <tr>
+ * <td>trace</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
+ * Object</td>
+ * <td>A definition of a TRACE operation on this path.</td>
+ * </tr>
+ * <tr>
+ * <td>servers</td>
+ * <td>[{@link org.eclipse.microprofile.openapi.models.servers.Server Server}
+ * Object]</td>
+ * <td>An alternative server array to service all operations in this path.</td>
+ * </tr>
+ * <tr>
+ * <td>parameters</td>
+ * <td>[{@link org.eclipse.microprofile.openapi.models.parameters.Parameter
+ * Parameter} Object |
+ * {@link org.eclipse.microprofile.openapi.models.parameters.Parameter
+ * Reference} Object]</td>
+ * <td>A list of parameters that are applicable for all the operations described
+ * under this path. These parameters can be overridden at the operation level,
+ * but cannot be removed there. The list MUST NOT include duplicated parameters.
+ * A unique parameter is defined by a combination of a name and location. The
+ * list can use the Reference Object to link to parameters that are defined at
+ * the OpenAPI Object's components/parameters.</td>
+ * </tr>
+ * </table>
+ * 
+ * @see <a href=
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#pathItemObject">OpenAPI
+ *      Specification Path Item Object</a>
  */
 public interface PathItem extends Constructible, Extensible {
 
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 a1db22108..f51cb1864 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
@@ -21,18 +21,46 @@
 
 /**
  * Paths
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#pathsObject"
+ * <p>
+ * Holds the relative paths to the individual endpoints and their operations.
+ * The path is appended to the URL from the Server Object in order to construct
+ * the full URL. The Paths MAY be empty, due to ACL constraints.
+ * <p>
+ * Patterned Fields
+ * <table border=1>
+ * <tr>
+ * <td>Field Pattern</td>
+ * <td>Type</td>
+ * <td>Description</td>
+ * </tr>
+ * <tr>
+ * <td>/{path}</td>
+ * <td>{@link org.eclipse.microprofile.openapi.models.PathItem "Path Item
+ * Object"}</td>
+ * <td>A relative path to an individual endpoint. The field name MUST begin with
+ * a slash. The path is appended (no relative URL resolution) to the expanded
+ * URL from the Server Object's url field in order to construct the full URL.
+ * Path templating is allowed. When matching URLs, concrete (non-templated)
+ * paths would be matched before their templated counterparts. Templated paths
+ * with the same hierarchy but different templated names MUST NOT exist as they
+ * are identical. In case of ambiguous matching, it's up to the tooling to
+ * decide which one to use.</td>
+ * </tr>
+ * </table>
+ * 
+ * @see <a
+ *      href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#pathsObject">OpenAPI
+ *      Specification Paths Object</a>
  */
 public interface Paths extends Constructible, Extensible, Map<String, PathItem> {
 
 	/**
-	   * Adds the given path item to this Paths and return this instance of Paths
-	   * 
-	   * @param String name
-	   * @param PathItem item
-	   * @return 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
+	  * @param item the path item added to the list of paths
+	  * @return the current Paths instance
+	  */
 	Paths addPathItem(String name, PathItem item);
 
 }
\ No newline at end of file
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 d63e64cef..0108f4752 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
@@ -25,16 +25,29 @@
 
 /**
  * Callback
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#callbackObject"
+ * <p>
+ * A map of possible out-of-band callbacks related to the parent operation. Each
+ * value in the map is a Path Item Object that describes a set of requests that
+ * may be initiated by the API provider and the expected responses. The key
+ * value used to identify the callback object is an expression, evaluated at
+ * runtime, that identifies a URL to use for the callback operation.
+ * 
+ * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#callbackObject">OpenAPI Specification Callback Object</a>
  */
 public interface Callback extends Constructible, Extensible, Map<String, PathItem> {
 
 	/**
-	   * Adds the given PathItem to this Callbacks's list of PathItems, with the given key as its key.
+	   * Adds the given PathItem to this Callback's list of PathItems using the string as its key.
 	   *
-	   * @param String name
-	   * @param PathItem item
+	   * The key that identifies the Path Item Object is a runtime expression that can be 
+	   * evaluated in the context of a runtime HTTP request/response to identify the URL 
+	   * to be used for the callback request. A simple example might be $request.body#/url. 
+	   * However, using a runtime expression the 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 item a path to add to this Callback's list of PathItems
 	   */
 	Callback addPathItem(String name, PathItem item);
 
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
index 6d14c1d8b..307b60062 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
@@ -23,90 +23,76 @@
 
 /**
  * Tag
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#tagObject"
+ * <p>
+ * An object to store metadata to be available in the OpenAPI document.
+ * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#tagObject">OpenAPI Specification Tag Object</a>
  */
 public interface Tag extends Constructible, Extensible {
 
 	/**
-	 * returns the name property from a Tag instance.
+	 * Returns the name property from a Tag instance.
 	 *
-	 * @return String name
+	 * @return the name property from this tag
 	 **/
-
 	String getName();
 
 	/**
-	 * Sets the name property of a Tag instance to the
-	 * parameter.
+	 * Sets the name property of a Tag instance to the given string.
 	 * 
-	 * @param name
+	 * @param name the name property for this tag
 	 */
-
 	void setName(String name);
 
 	/**
-	 * Sets the name property of a Tag instance to the
-	 * parameter and returns the instance.
+	 * Sets the name property of a Tag instance to the given string.
 	 * 
-	 * @param name
-	 * @return Tag instance with the set name property
+	 * @param name the name property for this tag
+	 * @return the current Tag instance
 	 */
-
 	Tag name(String name);
 
 	/**
-	 * returns the description property from a Tag instance.
+	 * Returns the description property from a Tag instance.
 	 *
-	 * @return String description
+	 * @return the description property from this tag
 	 **/
-
 	String getDescription();
 
 	/**
-	 * Sets the description property of a Tag instance to the
-	 * parameter.
+	 * Sets the description property of a Tag instance to the given string.
 	 * 
-	 * @param description
+	 * @param description the description property for this tag
 	 */
-
 	void setDescription(String description);
 
 	/**
-	 * Sets the description property of a Tag instance to the
-	 * parameter and returns the instance.
+	 * Sets the description property of a Tag instance to the given string.
 	 * 
-	 * @param description
-	 * @return Tag instance with the set description property
+	 * @param description the description property for this tag
+	 * @return the current Tag instance
 	 */
-
 	Tag description(String description);
 
 	/**
-	 * returns the externalDocs property from a Tag instance.
+	 * Returns the externalDocs property from a Tag instance.
 	 *
-	 * @return ExternalDocumentation externalDocs
+	 * @return additional external documentation from this tag
 	 **/
-
 	ExternalDocumentation getExternalDocs();
 
 	/**
-	 * Sets the externalDocs property of a Tag instance to the
-	 * parameter.
+	 * Sets the externalDocs property of a Tag instance to the given object.
 	 * 
-	 * @param externalDocs
+	 * @param externalDocs additional external documentation for this tag
 	 */
-
 	void setExternalDocs(ExternalDocumentation externalDocs);
 
 	/**
-	 * Sets the externalDocs property of a Tag instance to the
-	 * parameter and returns the instance.
+	 * Sets the externalDocs property of a Tag instance to the given object.
 	 * 
-	 * @param externalDocs
-	 * @return Tag instance with the set externalDocs property
+	 * @param externalDocs additional external documentation for this tag
+	 * @return the current Tag instance
 	 */
-
 	Tag externalDocs(ExternalDocumentation externalDocs);
 
 }
\ No newline at end of file

From 7405dbf37d2fef5ca9c66d1d4976fc23208ff165 Mon Sep 17 00:00:00 2001
From: Paul Gooderham <turkeyonmarblerye@gmail.com>
Date: Wed, 25 Oct 2017 13:36:54 -0400
Subject: [PATCH 14/23] Update the Javadocs and remove the Link.headers
 property because it is not in the spec. Delete LinkParameter because it is no
 longer used. 8732

Signed-off-by: Paul Gooderham <turkeyonmarblerye@gmail.com>
---
 .../openapi/models/links/Link.java            | 232 ++++++++++--------
 .../openapi/models/links/LinkParameter.java   |  53 ----
 2 files changed, 133 insertions(+), 152 deletions(-)
 delete mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/links/LinkParameter.java

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 4dd34add0..a80dff035 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
@@ -27,208 +27,242 @@
 
 /**
  * Link
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#linkObject"
+ * <p>
+ * The Link object represents a possible design-time link for a response. The
+ * presence of a link does not guarantee the caller's ability to successfully
+ * invoke it, rather it provides a known relationship and traversal mechanism
+ * between responses and other operations.
+ * <p>
+ * Unlike dynamic links (i.e. links provided in the response payload), the OAS
+ * linking mechanism does not require link information in the runtime response.
+ * <p>
+ * For computing links, and providing instructions to execute them, a runtime
+ * expression is used for accessing values in an operation and using them as
+ * parameters while invoking the linked operation.
+ * <p>
+ * Fixed Fields
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
+ * <tr>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td>reference</td>
+ * <td>string</td>
+ * <td>Allows for an external definition of this link. The referenced structure
+ * MUST be in the format of a Link Object. This field represents the $ref field
+ * in the OAS file. If there are conflicts between the referenced definition and
+ * this Link's definition, the behavior is undefined.</td>
+ * </tr>
+ * <tr>
+ * <td>operationRef</td>
+ * <td>string</td>
+ * <td>A relative or absolute reference to an OAS operation. This field is
+ * mutually exclusive of the operationId field, and MUST point to an Operation
+ * Object. Relative operationRef values MAY be used to locate an existing
+ * Operation Object in the OpenAPI definition.</td>
+ * </tr>
+ * <tr>
+ * <td>operationId</td>
+ * <td>string</td>
+ * <td>The name of an existing, resolvable OAS operation, as defined with a
+ * unique operationId. This field is mutually exclusive of the operationRef
+ * field.</td>
+ * </tr>
+ * <tr>
+ * <td>parameters</td>
+ * <td>Map[string, Any | {expression}]</td>
+ * <td>A map representing parameters to pass to an operation as specified with
+ * operationId or identified via operationRef. The key is the parameter name to
+ * be used, whereas the value can be a constant or an expression to be evaluated
+ * and passed to the linked operation. The parameter name can be qualified using
+ * the parameter location [{in}.]{name} for operations that use the same
+ * parameter name in different locations (e.g. path.id).</td>
+ * </tr>
+ * <tr>
+ * <td>requestBody</td>
+ * <td>{@link RequestBody Request Body Object} | runtime expression</td>
+ * <td>A literal value or runtime expression to use as a request body when
+ * calling the target operation.</td>
+ * </tr>
+ * <tr>
+ * <td>description</td>
+ * <td>string</td>
+ * <td>A description of the link. CommonMark syntax MAY be used for rich text
+ * representation.</td>
+ * </tr>
+ * <tr>
+ * <td>server</td>
+ * <td>{@link Server Server Object}</td>
+ * <td>A server object to be used by the target operation.</td>
+ * </tr>
+ * </table>
+ * A linked operation MUST be identified using either an operationRef or
+ * operationId. In the case of an operationId, it MUST be unique and resolved in
+ * the scope of the OAS document. Because of the potential for name clashes, the
+ * operationRef syntax is preferred for specifications with external references.
+ * <p>
+ * 
+ * @see <a href=
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#linkObject">
+ *      OpenAPI Specification Link Object</a>
  */
 public interface Link extends Constructible, Extensible {
 
 	/**
-	 * returns the server property from a Link instance.
+	 * Returns the server property from a Link instance.
 	 *
-	 * @return Server server
+	 * @return a server object to be used by the target operation
 	 **/
-
 	Server getServer();
 
 	/**
-	 * sets this Link's server property to the given server.
+	 * Sets this Link's server property to the given object.
 	 *
-	 * @param Server server
+	 * @param server  a server object to be used by the target operation
 	 */
 	void setServer(Server server);
 
 	/**
-	 * sets this Link's server property to the given server and
-	 * returns this instance of Link
+	 * Sets this Link's server property to the given object.
 	 *
-	 * @param Server server
-	 * @return Link
+	 * @param server  a server object to be used by the target operation
+	 * @return the current instance of Link
 	 */
 	Link server(Server server);
 
 	/**
-	 * returns the operationRef property from a Link instance.
+	 * Returns the operationRef property from a Link instance.
 	 *
-	 * @return String operationRef
+	 * @return a relative or absolute reference to an OAS operation
 	 **/
-
 	String getOperationRef();
 
 	/**
-	 * sets this Link's operationRef property to the given operationRef.
+	 * Sets this Link's operationRef property to the given string.
 	 *
-	 * @param String operationRef
+	 * @param operationRef  a relative or absolute reference to an OAS operation
 	 */
 	void setOperationRef(String operationRef);
 
 	/**
-	 * sets this Link's operationRef property to the given operationRef and
-	 * returns this instance of Link
+	 * Sets this Link's operationRef property to the given string.
 	 *
-	 * @param String operationRef
-	 * @return Link
+	 * @param operationRef  a relative or absolute reference to an OAS operation
+	 * @return the current instance of Link
 	 */
 	Link operationRef(String operationRef);
 
 	/**
-	 * returns the requestBody property from a Link instance.
+	 * Returns the requestBody property from a Link instance.
 	 *
-	 * @return RequestBody requestBody
+	 * @return a literal value or runtime expression to use as a request body when calling the target operation
 	 **/
-
 	RequestBody getRequestBody();
 
 	/**
-	 * sets this Link's requestBody property to the given requestBody.
+	 * Sets this Link's requestBody property to the given object.
 	 *
-	 * @param RequestBody requestBody
+	 * @param requestBody  a literal value or runtime expression to use as a request body when calling the target operation
 	 */
 	void setRequestBody(RequestBody requestBody);
 
 	/**
-	 * sets this Link's requestBody property to the given requestBody and
-	 * returns this instance of Link
+	 * Sets this Link's requestBody property to the given object.
 	 *
-	 * @param RequestBody requestBody
-	 * @return Link
+	 * @param requestBody  a literal value or runtime expression to use as a request body when calling the target operation
+	 * @return the current instance of Link
 	 */
 	Link requestBody(RequestBody requestBody);
 
 	/**
-	 * returns this Link's requestBody property for this instance of Link.
+	 * Returns the operationId property for this instance of Link.
 	 *
-	 * @param String operationId
+	 * @param operationId  the name of an existing, resolvable OAS operation
 	 */
 	String getOperationId();
 
 	/**
-	 * sets this Link's operationId property to the given operationId.
+	 * Sets this Link's operationId property to the given string.
 	 *
-	 * @param String operationId
+	 * @param operationId  the name of an existing, resolvable OAS operation
 	 */
 	void setOperationId(String operationId);
 
 	/**
-	 * sets this Link's operationId property to the given operationId and
-	 * returns this instance of Link
+	 * Sets this Link's operationId property to the given string.
 	 *
-	 * @param String operationId
-	 * @return Link
+	 * @param operationId  the name of an existing, resolvable OAS operation
+	 * @return the current instance of Link
 	 */
 	Link operationId(String operationId);
 
 	/**
-	 * returns the parameters property from a Link instance.
+	 * Returns the parameters property from this instance of Link.
 	 *
-	 * @return LinkParameters parameters
+	 * @return a map representing parameters to pass to this link's operation
 	 **/
 	Map<String, String> getParameters();
 
 	/**
-	 * sets this Link's parameters property to the given parameters.
+	 * Sets this Link's parameters property to the given map.
 	 *
-	 * @param LinkParameters parameters
+	 * @param parameters  a map representing parameters to pass to this link's operation
 	 */
 	void setParameters(Map<String, String> parameters);
 
 	/**
-	 * sets this Link's parameter property to the given parameter and
-	 * returns this instance of Link
+	 * Add a new parameter to the parameters property of this instance of Link. 
 	 *
-	 * @param String name
-	 * @param String parameter
-	 * @return 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
+	 * @return the current instance of Link
 	 */
 	Link parameters(String name, String parameter);
 
 	/**
-	 * returns the headers property from a Link instance.
-	 *
-	 * @return Headers headers
-	 **/
-
-	Map<String, Header> getHeaders();
-
-	/**
-	 * sets this Link's headers property to the given headers.
+	 * Returns the description property from a Link instance.
 	 *
-	 * @param Map&lt;String, Header&gt; headers
-	 */
-	void setHeaders(Map<String, Header> headers);
-
-	/**
-	 * sets this Link's headers property to the given headers and
-	 * returns this instance of Link
-	 *
-	 * @param Map&lt;String, Header&gt; headers
-	 * @return Link
-	 */
-	Link headers(Map<String, Header> headers);
-
-	/**
-	 * Adds the given Header to this Link's map of headers, with the given name as its key.
-	 *
-	 * @param String name
-	 * @param Header header
-	 * @return Link
-	 */
-	Link addHeaderObject(String name, Header header);
-
-	/**
-	 * returns the description property from a Link instance.
-	 *
-	 * @return String description
+	 * @return a description of the link
 	 **/
-
 	String getDescription();
 
 	/**
-	 * returns the description property from a Link instance.
+	 * Sets this Link's description property to the given string.
 	 *
-	 * @return String description
+	 * @param description  a description of the link
 	 **/
 	void setDescription(String description);
 
 	/**
-	 * sets this Link's description property to the given description and
-	 * returns this instance of Link
+	 * Sets this Link's description property to the given string.
 	 *
-	 * @param String description
-	 * @return Link
+	 * @param description  a description of the link
+	 * @return the current instance of Link
 	 */
 	Link description(String description);
 
 	/**
-	 * returns the $ref property from a Link instance.
+	 * Returns the reference property from a Link instance.
 	 *
-	 * @return String $ref
+	 * @return a reference to one of the components in this OpenAPI document
 	 **/
-	String get$ref();
+	String getReference();
 
 	/**
-	 * sets the $ref property for a Link instance.
+	 * Sets this Link's reference property to the given string.
 	 *
-	 * @param String $ref
+	 * @param reference  a reference to a link object in the components in this OpenAPI document
 	 **/
-	void set$ref(String $ref);
+	void setReference(String reference);
 
 	/**
-	 * sets this Link's $ref property to the given description and
-	 * returns this instance of Link
+	 * Sets this Link's reference property to the given string.
 	 *
-	 * @param String $ref
-	 * @return Link
+	 * @param reference  a reference to a link object in the components in this OpenAPI document
+	 * @return the current instance of Link
 	 */
-	Link $ref(String $ref);
+	Link reference(String reference);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/links/LinkParameter.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/links/LinkParameter.java
deleted file mode 100644
index 82e33a0b2..000000000
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/links/LinkParameter.java
+++ /dev/null
@@ -1,53 +0,0 @@
-/**
- * Copyright (c) 2017 Contributors to the Eclipse Foundation
- * Copyright 2017 SmartBear Software
- * <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.models.links;
-
-import org.eclipse.microprofile.openapi.models.Constructible;
-import org.eclipse.microprofile.openapi.models.Extensible;
-
-/**
- * LinkParameter
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#linkOParametersbject"
- */
-public interface LinkParameter extends Constructible, Extensible {
-
-	/**
-	   * returns the value property from a LinkParameter instance.
-	   *
-	   * @return String value
-	   **/
-	String getValue();
-
-	/**
-	   * sets this LinkParameter's value property to the given value.
-	   *
-	   * @param String value
-	   */
-	void setValue(String value);
-
-	/**
-	   * sets this LinkParameter's value property to the given value and
-	   * returns this instance of LinkParameter
-	   *
-	   * @param String value
-	   * @return LinkParameter
-	   */
-	LinkParameter value(String value);
-
-}
\ No newline at end of file

From afd385a0b05cfd7273963a1de6cd514cbeea55aa Mon Sep 17 00:00:00 2001
From: Paul Gooderham <turkeyonmarblerye@gmail.com>
Date: Wed, 25 Oct 2017 15:14:16 -0400
Subject: [PATCH 15/23] Update the Javadocs. 8732

Signed-off-by: Paul Gooderham <turkeyonmarblerye@gmail.com>
---
 .../openapi/models/Components.java            |  48 +-
 .../openapi/models/ExternalDocumentation.java |  10 +-
 .../microprofile/openapi/models/OpenAPI.java  |  31 +-
 .../openapi/models/Operation.java             | 485 ++++++++++--------
 .../microprofile/openapi/models/Paths.java    |  15 +-
 .../openapi/models/callbacks/Callback.java    |   2 +-
 .../openapi/models/examples/Example.java      | 139 +++--
 .../openapi/models/media/Content.java         |  16 +-
 .../microprofile/openapi/models/tags/Tag.java |  31 +-
 9 files changed, 463 insertions(+), 314 deletions(-)

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 9bd0b18f1..5010a198c 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
@@ -37,74 +37,78 @@
  * they are explicitly referenced from properties outside the components object.
  * <p>
  * Fixed Fields
- * <table border=1>
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
  * <tr>
- * <td>Field Name</td>
- * <td>Type</td>
- * <td>Description</td>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
  * </tr>
  * <tr>
  * <td>schemas</td>
- * <td>Map[string, {@link media.Schema Schema} Object | Reference Object]</td>
+ * <td>Map[string, {@link Schema Schema Object } | {@link Schema Reference Object}]</td>
  * <td>An object to hold reusable Schema Objects.</td>
  * </tr>
  * <tr>
  * <td>responses</td>
- * <td>Map[string, {@link responses.ApiResponse Response} Object | Reference
- * Object]</td>
+ * <td>Map[string, {@link ApiResponse Response Object } | {@link ApiResponse Reference
+ * Object}]</td>
  * <td>An object to hold reusable Response Objects.</td>
  * </tr>
  * <tr>
  * <td>parameters</td>
- * <td>Map[string, {@link parameters.Parameter Parameter} Object | Reference
- * Object]</td>
+ * <td>Map[string, {@link Parameter Parameter Object } | {@link Parameter Reference
+ * Object}]</td>
  * <td>An object to hold reusable Parameter Objects.</td>
  * </tr>
  * <tr>
  * <td>examples</td>
- * <td>Map[string, {@link examples.Example Example} Object | Reference
- * Object]</td>
+ * <td>Map[string, {@link Example Example Object } | {@link Example Reference
+ * Object}]</td>
  * <td>An object to hold reusable Example Objects.</td>
  * </tr>
  * <tr>
  * <td>requestBodies</td>
- * <td>Map[string, {@link parameters.RequestBody Request Body} Object |
- * Reference Object]</td>
+ * <td>Map[string, {@link RequestBody Request Body Object } |
+ * {@link RequestBody Reference Object}]</td>
  * <td>An object to hold reusable Request Body Objects.</td>
  * </tr>
  * <tr>
  * <td>headers</td>
- * <td>Map[string, {@link headers.Header Header} Object | Reference Object]</td>
+ * <td>Map[string, {@link Header Header Object } | {@link Header Reference Object}]</td>
  * <td>An object to hold reusable Header Objects.</td>
  * </tr>
  * <tr>
  * <td>securitySchemes</td>
- * <td>Map[string, {@link security.SecurityScheme Security Scheme} Object |
- * Reference Object]</td>
+ * <td>Map[string, {@link SecurityScheme Security Scheme Object } |
+ * {@link SecurityScheme Reference Object}]</td>
  * <td>An object to hold reusable Security Scheme Objects.</td>
  * </tr>
  * <tr>
  * <td>links</td>
- * <td>Map[string, {@link links.Link Link} Object | Reference Object]</td>
+ * <td>Map[string, {@link Link Link Object } | {@link Link Reference Object}]</td>
  * <td>An object to hold reusable Link Objects.</td>
  * </tr>
  * <tr>
  * <td>callbacks</td>
- * <td>Map[string, {@link callbacks.Callback Callback} Object | Reference
- * Object]</td>
+ * <td>Map[string, {@link Callback Callback Object } | {@link Callback Reference
+ * Object}]</td>
  * <td>An object to hold reusable Callback Objects.</td>
  * </tr>
  * </table>
  * <p>
  * All the fixed fields declared above are objects that MUST use keys that match
- * the regular expression: ^[a-zA-Z0-9\.\-_]+$.
+ * the regular expression: <code>^[a-zA-Z0-9\.\-_]+$</code>.
  * <p>
  * Field Name Examples:
  * <ul>
- * <li>User</li> <li>User_1</li> <li>User_Name</li> <li>user-name</li> <li>my.org.User</li>
+ * <li>User</li> 
+ * <li>User_1</li> 
+ * <li>User_Name</li> 
+ * <li>user-name</li> 
+ * <li>my.org.User</li>
  * </ul>
  * @see <a href=
- *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#componentsObject">
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#componentsObject">
  *      OpenAPI Specification Components Object</a>
  */
 public interface Components extends Constructible, Extensible {
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
index a89fb9482..38057b37f 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
@@ -23,11 +23,11 @@
  * Allows referencing an external resource for extended documentation.
  * <p>
  * Fixed Fields
- * <table border=1>
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
  * <tr>
- * <td>Field Name</td>
- * <td>Type</td>
- * <td>Description</td>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
  * </tr>
  * <tr>
  * <td>description</td>
@@ -43,7 +43,7 @@
  * </table>
  * 
  * @see <a href=
- *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#externalDocumentationObject">OpenAPI
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#externalDocumentationObject">OpenAPI
  *      Specification External Documentation Object</a>
  */
 public interface ExternalDocumentation extends Constructible, Extensible {
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
index a99a4fea8..41e415b0c 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
@@ -31,15 +31,15 @@
  * <p>
  * This is the root document object of the OpenAPI document. It contains the
  * following required and optional fields.
- * <table border=1>
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
  * <tr>
- * <td>Field Name</td>
- * <td>Type</td>
- * <td>Description</td>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
  * </tr>
  * <tr>
  * <td>openapi</td>
- * <td>String</td>
+ * <td>string</td>
  * <td>REQUIRED. This string MUST be the semantic version number of the OpenAPI
  * Specification version that the OpenAPI document uses. The openapi field
  * SHOULD be used by tooling specifications and clients to interpret the OpenAPI
@@ -47,31 +47,30 @@
  * </tr>
  * <tr>
  * <td>info</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.info.Info Info}</td>
+ * <td>{@link Info Info Object}</td>
  * <td>REQUIRED. Provides metadata about the API. The metadata MAY be used by
  * tooling as required.</td>
  * </tr>
  * <tr>
  * <td>servers</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.servers.Server Server}</td>
+ * <td>[{@link Server Server Object}]</td>
  * <td>An array of Server Objects, which provide connectivity information to a
  * target server. If the servers property is not provided, or is an empty array,
  * the default value would be a Server Object with a url value of /.</td>
  * </tr>
  * <tr>
  * <td>paths</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.Paths Paths} Object</td>
+ * <td>{@link Paths Paths Object}</td>
  * <td>REQUIRED. The available paths and operations for the API.</td>
  * </tr>
  * <tr>
  * <td>components</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.Components Components}</td>
+ * <td>{@link Components Components Object}</td>
  * <td>An element to hold various schemas for the specification.</td>
  * </tr>
  * <tr>
  * <td>security</td>
- * <td>{@link
- * org.eclipse.microprofile.openapi.models.security.SecurityRequirement SecurityRequirement}</td>
+ * <td>[{@link SecurityRequirement SecurityRequirement Object}]</td>
  * <td>A declaration of which security mechanisms can be used across the API.
  * The list of values includes alternative security requirement objects that can
  * be used. Only one of the security requirement objects need to be satisfied to
@@ -79,7 +78,7 @@
  * </tr>
  * <tr>
  * <td>tags</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.tags.Tag Tag}</td>
+ * <td>[{@link Tag Tag Object}]</td>
  * <td>A list of tags used by the specification with additional metadata. The
  * order of the tags can be used to reflect on their order by the parsing tools.
  * Not all tags that are used by the Operation Object must be declared. The tags
@@ -88,12 +87,12 @@
  * </tr>
  * <tr>
  * <td>externalDocs</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.ExternalDocumentation ExternalDocumentation}</td>
+ * <td>{@link ExternalDocumentation External Documentation Object}</td>
  * <td>Additional external documentation.</td>
  * </tr>
  * </table>
  * 
- * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md">OpenAPI Specification</a>
+ * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#openapi-object">OpenAPI Specification OpenAPI Object</a>
  */
 public interface OpenAPI extends Constructible, Extensible {
 
@@ -102,7 +101,6 @@ public interface OpenAPI extends Constructible, Extensible {
 	  *
 	  * @return the semantic version number of the OpenAPI Specification version that the OpenAPI document uses
 	  **/
-
 	String getOpenapi();
 
 	/**
@@ -125,7 +123,6 @@ public interface OpenAPI extends Constructible, Extensible {
 	  *
 	  * @return metadata about the API
 	  **/
-
 	Info getInfo();
 
 	/**
@@ -170,7 +167,6 @@ public interface OpenAPI extends Constructible, Extensible {
 	  *
 	  * @return Server objects which provide connectivity information to target servers
 	  **/
-
 	List<Server> getServers();
 
 	/**
@@ -201,7 +197,6 @@ public interface OpenAPI extends Constructible, Extensible {
 	  *
 	  * @return which security mechanisms can be used across the API
 	  **/
-
 	List<SecurityRequirement> getSecurity();
 
 	/**
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 aee97e966..da5e6b088 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
@@ -29,332 +29,407 @@
 
 /**
  * Operation
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#operationObject"
+ * <p>
+ * Describes a single API operation on a path.
+ * <p>
+ * Fixed Fields
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
+ * <tr>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td>tags</td>
+ * <td>[string]</td>
+ * <td>A list of tags for API documentation control. Tags can be used for
+ * logical grouping of operations by resources or any other qualifier.</td>
+ * </tr>
+ * <tr>
+ * <td>summary</td>
+ * <td>string</td>
+ * <td>A short summary of what the operation does.</td>
+ * </tr>
+ * <tr>
+ * <td>description</td>
+ * <td>string</td>
+ * <td>A verbose explanation of the operation behavior. CommonMark syntax MAY be
+ * used for rich text representation.</td>
+ * </tr>
+ * <tr>
+ * <td>externalDocs</td>
+ * <td>{@link ExternalDocumentation External Documentation Object }</td>
+ * <td>Additional external documentation for this operation.</td>
+ * </tr>
+ * <tr>
+ * <td>operationId</td>
+ * <td>string</td>
+ * <td>Unique string used to identify the operation. The id MUST be unique among
+ * all operations described in the API. Tools and libraries MAY use the
+ * operationId to uniquely identify an operation, therefore, it is RECOMMENDED
+ * to follow common programming naming conventions.</td>
+ * </tr>
+ * <tr>
+ * <td>parameters</td>
+ * <td>[{@link Parameter Parameter Object } | {@link Parameter Reference Object}]</td>
+ * <td>A list of parameters that are applicable for this operation. If a
+ * parameter is already defined at the Path Item, the new definition will
+ * override it but can never remove it. The list MUST NOT include duplicated
+ * parameters. A unique parameter is defined by a combination of a name and
+ * location. The list can use the Reference Object to link to parameters that
+ * are defined at the OpenAPI Object's components/parameters.</td>
+ * </tr>
+ * <tr>
+ * <td>requestBody</td>
+ * <td>{@link RequestBody Request Body Object } | {@link RequestBody Reference
+ * Object}</td>
+ * <td>The request body applicable for this operation. The requestBody is only
+ * supported in HTTP methods where the HTTP 1.1 specification RFC7231 has
+ * explicitly defined semantics for request bodies. In other cases where the
+ * HTTP spec is vague, requestBody SHALL be ignored by consumers.</td>
+ * </tr>
+ * <tr>
+ * <td>responses</td>
+ * <td>{@link ApiResponses Responses Object }</td>
+ * <td>REQUIRED. The list of possible responses as they are returned from
+ * executing this operation.</td>
+ * </tr>
+ * <tr>
+ * <td>callbacks</td>
+ * <td>Map[string, {@link Callback Callback Object } | {@link Callback Reference
+ * Object}]</td>
+ * <td>A map of possible out-of band callbacks related to the parent operation.
+ * The key is a unique identifier for the Callback Object. Each value in the map
+ * is a Callback Object that describes a request that may be initiated by the
+ * API provider and the expected responses. The key value used to identify the
+ * callback object is an expression, evaluated at runtime, that identifies a URL
+ * to use for the callback operation.</td>
+ * </tr>
+ * <tr>
+ * <td>deprecated</td>
+ * <td>boolean</td>
+ * <td>Declares this operation to be deprecated. Consumers SHOULD refrain from
+ * usage of the declared operation. Default value is false.</td>
+ * </tr>
+ * <tr>
+ * <td>security</td>
+ * <td>[{@link SecurityRequirement Security Requirement Object }]</td>
+ * <td>A declaration of which security mechanisms can be used for this
+ * operation. The list of values includes alternative security requirement
+ * objects that can be used. Only one of the security requirement objects need
+ * to be satisfied to authorize a request. This definition overrides any
+ * declared top-level security. To remove a top-level security declaration, an
+ * empty array can be used.</td>
+ * </tr>
+ * <tr>
+ * <td>servers</td>
+ * <td>[{@link Server Server Object }]</td>
+ * <td>An alternative server array to service this operation. If an alternative
+ * server object is specified at the Path Item Object or Root level, it will be
+ * overridden by this value.</td>
+ * </tr>
+ * </table>
+ * 
+ * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject">OpenAPI Specification Operation Object</a>
  */
 public interface Operation extends Constructible, Extensible {
 
 	/**
-	   * returns the tags property from a Operation instance.
-	   *
-	   * @return List&lt;String&gt; tags
-	   **/
-
+	 * Returns the tags property from an Operation instance.
+	 *
+	 * @return a list of the operation's tags
+	 **/
 	List<String> getTags();
 
 	/**
-	   * sets this Operation's tags property to the given Tags.
-	   *
-	   * @param List&lt;String&gt;tags
-	   */
+	 * Sets this Operation's tags property to the given tags.
+	 *
+	 * @param tags a list of tags for API documentation control 
+	 **/
 	void setTags(List<String> tags);
 
 	/**
-	   * sets this Operation's tags property to the given tags and
-	   * returns this instance of Operation
-	   *
-	   * @param List&lt;String&gt;tags
-	   * @return Operation
-	   */
+	 * Sets this Operation's tags property to the given tags.
+	 *
+	 * @param tags a list of tags for API documentation control 
+	 * @return the current Operation object
+	 **/
 	Operation tags(List<String> tags);
 
 	/**
-	   * Adds the given tagsItem to this Operation's list of tags, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param String tagsItem
-	   * @return Operation
-	   */
+	 * Adds the given tag to this Operation's list of tags.
+	 *
+	 * @param tagsItem a tag for API documentation control
+	 * @return the current Operation object
+	 **/
 	Operation addTagsItem(String tagsItem);
 
 	/**
-	   * returns the summary property from a Operation instance.
-	   *
-	   * @return String summary
-	   **/
-
+	 * Returns the summary property from an Operation instance.
+	 *
+	 * @return a short summary of what the operation does
+	 **/
 	String getSummary();
 
 	/**
-	   * sets this Operation's summary property to the given summary.
-	   *
-	   * @param String summary
-	   */
+	 * Sets this Operation's summary property to the given string.
+	 *
+	 * @param summary a short summary of what the operation does
+	 **/
 	void setSummary(String summary);
 
 	/**
-	   * sets this Operation's summary property to the given summary and
-	   * returns this instance of Operation
-	   *
-	   * @param String summary
-	   * @return Operation
-	   */
+	 * Sets this Operation's summary property to the given string.
+	 *
+	 * @param summary a short summary of what the operation does
+	 * @return the current Operation object
+	 **/
 	Operation summary(String summary);
 
 	/**
-	   * returns the description property from a Operation instance.
-	   *
-	   * @return String description
-	   **/
+	 * Returns the description property from an Operation instance.
+	 *
+	 * @return a verbose explanation of the operation behavior
+	 **/
 	String getDescription();
 
 	/**
-	   * sets this Operation's description property to the given description.
-	   *
-	   * @param String description
-	   */
+	 * Sets this Operation's description property to the given string.
+	 *
+	 * @param description a verbose explanation of the operation behavior
+	 **/
 	void setDescription(String description);
 
 	/**
-	   * sets this Operation's description property to the given description and
-	   * returns this instance of Operation
-	   *
-	   * @param String description
-	   * @return Operation
-	   */
+	 * Sets this Operation's description property to the given string.
+	 *
+	 * @param description a verbose explanation of the operation behavior
+	 * @return the current Operation object
+	 **/
 	Operation description(String description);
 
 	/**
-	   * returns the externalDocs property from a Operation instance.
-	   *
-	   * @return ExternalDocumentation externalDocs
-	   **/
-
+	 * Returns the externalDocs property from an Operation instance.
+	 *
+	 * @return additional external documentation for this operation
+	 **/
 	ExternalDocumentation getExternalDocs();
 
 	/**
-	   * sets this Operation's externalDocs property to the given externalDocs.
-	   *
-	   * @param ExternalDocumentation externalDocs
-	   */
+	 * Sets this Operation's externalDocs property to the given object.
+	 *
+	 * @param externalDocs additional external documentation for this operation
+	 **/
 	void setExternalDocs(ExternalDocumentation externalDocs);
 
 	/**
-	   * sets this Operation's externalDocs property to the given externalDocs and
-	   * returns this instance of Operation
-	   *
-	   * @param ExternalDocumentation externalDocs
-	   * @return Operation
-	   */
+	 * Sets this Operation's externalDocs property to the given object.
+	 *
+	 * @param externalDocs additional external documentation for this operation
+	 * @return the current Operation object
+	 **/
 	Operation externalDocs(ExternalDocumentation externalDocs);
 
 	/**
-	   * returns the operationId property from a Operation instance.
-	   *
-	   * @return String operationId
-	   **/
-
+	 * Returns the operationId property from an Operation instance.
+	 *
+	 * @return unique string used to identify the operation
+	 **/
 	String getOperationId();
 
 	/**
-	   * sets this Operation's operationId property to the given operationId.
-	   *
-	   * @param String operationId
-	   */
+	 * Sets this Operation's operationId property to the given string.
+	 *
+	 * @param operationId unique string used to identify the operation
+	 **/
 	void setOperationId(String operationId);
 
 	/**
-	   * sets this Operation's operationId property to the given operationId and
-	   * returns this instance of Operation
-	   *
-	   * @param String operationId
-	   * @return Operation
-	   */
+	 * Sets this Operation's operationId property to the given string.
+	 *
+	 * @param operationId unique string used to identify the operation
+	 * @return the current Operation object
+	 **/
 	Operation operationId(String operationId);
 
 	/**
-	   * returns the parameters property from a Operation instance.
-	   *
-	   * @return List&lt;Parameter&gt; parameters
-	   **/
-
+	 * Returns the parameters property from an Operation instance.
+	 *
+	 * @return a list of parameters that are applicable for this operation
+	 **/
 	List<Parameter> getParameters();
 
 	/**
-	   * sets this Operation's parameters property to the given parameters.
-	   *
-	   * @param List&lt;Parameter&gt;parameters
-	   */
+	 * Sets this Operation's parameters property to the given parameter list.
+	 *
+	 * @param parameters a list of parameters that are applicable for this operation
+	 **/
 	void setParameters(List<Parameter> parameters);
 
 	/**
-	   * sets this Operation's parameters property to the given parameters and
-	   * returns this instance of Operation
-	   *
-	   * @param List&lt;Parameter&gt;parameters
-	   * @return Operation
-	   */
+	 * Sets this Operation's parameters property to the given parameter list.
+	 *
+	 * @param parameters a list of parameters that are applicable for this operation
+	 * @return the current Operation object
+	 **/
 	Operation parameters(List<Parameter> parameters);
 
 	/**
-	   * Adds the given parametersItem to this Operation's list of parameters, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param Parameter parametersItem
-	   * @return Operation
-	   */
+	 * Adds the given parameter item to this Operation's list of parameters.
+	 *
+	 * @param parametersItem a parameter that is applicable for this operation
+	 * @return the current Operation object
+	 **/
 	Operation addParametersItem(Parameter parametersItem);
 
 	/**
-	   * returns the requestBody property from a Operation instance.
-	   *
-	   * @return RequestBody requestBody
-	   **/
-
+	 * Returns the requestBody property from an Operation instance.
+	 *
+	 * @return the request body applicable for this operation
+	 **/
 	RequestBody getRequestBody();
 
 	/**
-	   * sets this Operation's requestBody property to the given requestBody.
-	   *
-	   * @param RequestBody requestBody
-	   */
+	 * Sets this Operation's requestBody property to the given object.
+	 *
+	 * @param requestBody the request body applicable for this operation
+	 **/
 	void setRequestBody(RequestBody requestBody);
 
 	/**
-	   * sets this Operation's requestBody property to the given requestBody and
-	   * returns this instance of Operation
-	   *
-	   * @param RequestBody requestBody
-	   * @return Operation
-	   */
+	 * Sets this Operation's requestBody property to the given object.
+	 *
+	 * @param requestBody the request body applicable for this operation
+	 * @return the current Operation object
+	 **/
 	Operation requestBody(RequestBody requestBody);
 
 	/**
-	   * returns the responses property from a Operation instance.
-	   *
-	   * @return ApiResponses responses
-	   **/
-
+	 * Returns the responses property from an Operation instance.
+	 *
+	 * @return collection of possible responses from executing this operation
+	 **/
 	ApiResponses getResponses();
 
 	/**
-	   * sets this Operation's responses property to the given responses.
-	   *
-	   * @param ApiResponses responses
-	   */
+	 * Sets this Operation's responses property to the given responses.
+	 *
+	 * @param responses collection of possible responses from executing this operation
+	 **/
 	void setResponses(ApiResponses responses);
 
 	/**
-	   * sets this Operation's responses property to the given responses and
-	   * returns this instance of Operation
-	   *
-	   * @param ApiResponses responses
-	   * @return Operation
-	   */
+	 * Sets this Operation's responses property to the given responses.
+	 *
+	 * @param responses collection of possible responses from executing this operation
+	 * @return the current Operation object
+	 **/
 	Operation responses(ApiResponses responses);
 
 	/**
-	   * returns the callbacks property from a Operation instance.
-	   *
-	   * @return Callbacks callbacks
-	   **/
-
+	 * Returns the callbacks property from an Operation instance.
+	 *
+	 * @return map of possible out-of-band callbacks related to the operation
+	 **/
 	Map<String, Callback> getCallbacks();
 
 	/**
-	   * sets this Operation's callbacks property to the given callbacks.
-	   *
-	   * @param Map&lt;String, Callback&gt; callbacks
-	   */
+	 * Sets this Operation's callbacks property to the given map.
+	 *
+	 * @param callbacks map of possible out-of-band callbacks related to the operation.
+	 * The key value must be the correct format for this field.
+	 **/
 	void setCallbacks(Map<String, Callback> callbacks);
 
 	/**
-	   * sets this Operation's callbacks property to the given callbacks and
-	   * returns this instance of Operation
-	   *
-	   * @param Map&lt;String, Callback&gt; callbacks
-	   * @return Operation
-	   */
+	 * Sets this Operation's callbacks property to the given map.
+	 *
+	 * @param callbacks map of possible out-of-band callbacks related to the operation.
+	 * The key value must be the correct format for this field.
+	 * @return the current Operation object
+	 **/
 	Operation callbacks(Map<String, Callback> callbacks);
 
 	/**
-	   * returns the deprecated property from a Operation instance.
-	   *
-	   * @return Boolean deprecated
-	   **/
-
+	 * Returns the deprecated property from an Operation instance.
+	 *
+	 * @return declaration whether this operation is deprecated
+	 **/
 	Boolean getDeprecated();
 
 	/**
-	   * sets this Operation's deprecated property to the given deprecated.
-	   *
-	   * @param Boolean deprecated
-	   */
+	 * Sets this Operation's deprecated property to the given value.
+	 *
+	 * @param deprecated declaration whether this operation is deprecated
+	 **/
 	void setDeprecated(Boolean deprecated);
 
 	/**
-	   * sets this Operation's deprecated property to the given deprecated and
-	   * returns this instance of Operation
-	   *
-	   * @param Boolean deprecated
-	   * @return Operation
-	   */
+	 * Sets this Operation's deprecated property to the given value.
+	 *
+	 * @param deprecated declaration whether this operation is deprecated
+	 * @return the current Operation object
+	 **/
 	Operation deprecated(Boolean deprecated);
 
 	/**
-	   * returns the security property from a Operation instance.
-	   *
-	   * @return List&lt;SecurityRequirement&gt; security
-	   **/
-
+	 * Returns the security property from an Operation instance.
+	 *
+	 * @return a list of which security mechanisms can be used for this operation
+	 **/
 	List<SecurityRequirement> getSecurity();
 
 	/**
-	   * sets this Operation's security property to the given security.
-	   *
-	   * @param List&lt;SecurityRequirement&gt; security
-	   */
+	 * Sets this Operation's security property to the given list.
+	 *
+	 * @param security list of which security mechanisms can be used for this operation
+	 **/
 	void setSecurity(List<SecurityRequirement> security);
 
 	/**
-	   * sets this Operation's security property to the given security and
-	   * returns this instance of Operation
-	   *
-	   * @param List&lt;SecurityRequirement&gt;security
-	   * @return Operation
-	   */
+	 * Sets this Operation's security property to the given list.
+	 *
+	 * @param security list of which security mechanisms can be used for this operation
+	 * @return the current Operation object
+	 **/
 	Operation security(List<SecurityRequirement> security);
 
 	/**
-	   * Adds the given securityItem to this Operation's list of securityItems, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param SecurityRequirement securityItem
-	   * @return Operation
-	   */
+	 * Adds the given security requirement item to this Operation's list of security mechanisms.
+	 *
+	 * @param securityItem security mechanism which can be used for this operation
+	 * @return the current Operation object
+	 **/
 	Operation addSecurityItem(SecurityRequirement securityItem);
 
 	/**
-	   * returns the servers property from a Operation instance.
-	   *
-	   * @return List&lt;Server&gt; servers
-	   **/
-
+	 * Returns the servers property from an Operation instance.
+	 *
+	 * @return a list of servers to service this operation
+	 **/
 	List<Server> getServers();
 
 	/**
-	   * sets this Operation's servers property to the given servers.
-	   *
-	   * @param List&lt;Server&gt; servers
-	   */
+	 * Sets this Operation's servers property to the given list.
+	 *
+	 * @param servers list of servers to service this operation
+	 **/
 	void setServers(List<Server> servers);
 
 	/**
-	   * sets this Operation's servers property to the given servers and
-	   * returns this instance of Operation
-	   *
-	   * @param List&lt;Server&gt;servers
-	   * @return Operation
-	   */
+	 * Sets this Operation's servers property to the given list.
+	 *
+	 * @param servers list of servers to service this operation
+	 * @return the current Operation object
+	 **/
 	Operation servers(List<Server> servers);
 
 	/**
-	   * Adds the given serversItem to this Operation's list of serversItem, with the given key as its key.
-	   *
-	   * @param String key
-	   * @param Server serversItem
-	   * @return Operation
-	   */
+	 * Adds the given server to this Operation's list of servers.
+	 *
+	 * @param serversItem server which can service this operation
+	 * @return the current Operation object
+	 **/
 	Operation addServersItem(Server serversItem);
 
 }
\ No newline at end of file
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 f51cb1864..251c186ba 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
@@ -27,16 +27,15 @@
  * the full URL. The Paths MAY be empty, due to ACL constraints.
  * <p>
  * Patterned Fields
- * <table border=1>
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
  * <tr>
- * <td>Field Pattern</td>
- * <td>Type</td>
- * <td>Description</td>
+ * <th>Field Pattern</th>
+ * <th>Type</th>
+ * <th>Description</th>
  * </tr>
  * <tr>
  * <td>/{path}</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.PathItem "Path Item
- * Object"}</td>
+ * <td>{@link PathItem Path Item Object}</td>
  * <td>A relative path to an individual endpoint. The field name MUST begin with
  * a slash. The path is appended (no relative URL resolution) to the expanded
  * URL from the Server Object's url field in order to construct the full URL.
@@ -49,8 +48,8 @@
  * </table>
  * 
  * @see <a
- *      href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#pathsObject">OpenAPI
- *      Specification Paths Object</a>
+ *      href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathsObject">
+ *      OpenAPI Specification Paths Object</a>
  */
 public interface Paths extends Constructible, Extensible, Map<String, PathItem> {
 
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 0108f4752..3761bcaa6 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
@@ -32,7 +32,7 @@
  * value used to identify the callback object is an expression, evaluated at
  * runtime, that identifies a URL to use for the callback operation.
  * 
- * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#callbackObject">OpenAPI Specification Callback Object</a>
+ * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#callbackObject">OpenAPI Specification Callback Object</a>
  */
 public interface Callback extends Constructible, Extensible, Map<String, PathItem> {
 
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
index 094674d77..0d67d9e5e 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
@@ -22,126 +22,171 @@
 
 /**
  * Example
+ * <p>
+ * An object containing sample data for the related object.
+ * <p>
+ * Fixed Fields
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
+ * <tr>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td>reference</td>
+ * <td>string</td>
+ * <td>Allows for an external definition of this example. The referenced
+ * structure MUST be in the format of an Example Object. This field represents
+ * the $ref field in the OAS file. If there are conflicts between the referenced
+ * definition and this Example's definition, the behavior is undefined.</td>
+ * </tr>
+ * <tr>
+ * <td>summary</td>
+ * <td>string</td>
+ * <td>Short description for the example.</td>
+ * </tr>
+ * <tr>
+ * <td>description</td>
+ * <td>string</td>
+ * <td>Long description for the example. CommonMark syntax MAY be used for rich
+ * text representation.</td>
+ * </tr>
+ * <tr>
+ * <td>value</td>
+ * <td>Any</td>
+ * <td>Embedded literal example. The value field and externalValue field are
+ * mutually exclusive. To represent examples of media types that cannot
+ * naturally be represented in JSON or YAML, use a string value to contain the
+ * example, escaping where necessary.</td>
+ * </tr>
+ * <tr>
+ * <td>externalValue</td>
+ * <td>string</td>
+ * <td>A URL that points to the literal example. This provides the capability to
+ * reference examples that cannot easily be included in JSON or YAML documents.
+ * The value field and externalValue field are mutually exclusive.</td>
+ * </tr>
+ * </table>
+ * <p>
+ * In all cases, the example value is expected to be compatible with the type
+ * schema of its associated value. Tooling implementations MAY choose to
+ * validate compatibility automatically, and reject the example value(s) if
+ * incompatible.
+ * 
+ * @see <a href=
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#exampleObject">OpenAPI
+ *      Specification Example Object</a>
  */
 public interface Example extends Constructible, Extensible {
 
 	/**
-	 * returns the summary property from a Example instance.
+	 * Returns the summary property from an Example instance.
 	 *
-	 * @return String summary
+	 * @return short description of the example
 	 **/
-
 	String getSummary();
 
 	/**
-	 * sets this Example's summary property to the given summary.
+	 * Sets this Example's summary property to the given string.
 	 *
-	 * @param String summary
+	 * @param summary short description of the example
 	 */
 	void setSummary(String summary);
 
 	/**
-	 * sets this Example's summary property to the given summary and
-	 * returns this instance of Example
+	 * Sets this Example's summary property to the given string.
 	 *
-	 * @param String summary
-	 * @return Example
+	 * @param summary short description of the example
+	 * @return the current Example object
 	 */
 	Example summary(String summary);
 
 	/**
-	 * returns the description property from a Example instance.
+	 * Returns the description property from an Example instance.
 	 *
-	 * @return String description
+	 * @return long description of the example
 	 **/
-
 	String getDescription();
 
 	/**
-	 * sets this Example's description property to the given description.
+	 * Sets this Example's description property to the given string.
 	 *
-	 * @param String description
+	 * @param description long description of the example
 	 */
 	void setDescription(String description);
 
 	/**
-	 * sets this Example's description property to the given description and
-	 * returns this instance of Example
+	 * Sets this Example's description property to the given string.
 	 *
-	 * @param String description
-	 * @return Example
+	 * @param description long description of the example
+	 * @return the current Example object
 	 */
 	Example description(String description);
 
 	/**
-	 * returns the value property from a Example instance.
+	 * Returns the value property from an Example instance.
 	 *
-	 * @return Object value
+	 * @return embedded literal example object
 	 **/
-
 	Object getValue();
 
 	/**
-	 * sets this Example's value property to the given value.
+	 * Sets this Example's value property to the given value.
 	 *
-	 * @param Object value
+	 * @param value a literal example object
 	 */
 	void setValue(Object value);
 
 	/**
-	 * sets this Example's value property to the given value and
-	 * returns this instance of Example
+	 * Sets this Example's value property to the given value.
 	 *
-	 * @param Object value
-	 * @return Example
+	 * @param value a literal example object
+	 * @return the current Example object
 	 */
 	Example value(Object value);
 
 	/**
-	 * returns the externalValue property from a Example instance.
+	 * Returns the externalValue property from an Example instance.
 	 *
-	 * @return String externalValue
+	 * @return URL that points to the literal example
 	 **/
-
 	String getExternalValue();
 
 	/**
-	 * sets this Example's externalValue property to the given externalValue.
+	 * Sets this Example's externalValue property to the given string.
 	 *
-	 * @param String externalValue
+	 * @param externalValue URL that points to the literal example
 	 */
 	void setExternalValue(String externalValue);
 
 	/**
-	 * sets this Example's externalValue property to the given externalValue and
-	 * returns this instance of Example
+	 * Sets this Example's externalValue property to the given string.
 	 *
-	 * @param String externalValue
-	 * @return Example
+	 * @param externalValue URL that points to the literal example
+	 * @return the current Example object
 	 */
 	Example externalValue(String externalValue);
 
 	/**
-	 * returns the $ref property from a Example instance.
+	 * Returns the reference property from an Example instance.
 	 *
-	 * @return String $ref
+	 * @return a reference to an example object in the components in this OpenAPI document
 	 */
-	String get$ref();
+	String getReference();
 
 	/**
-	 * sets this Example's $ref property to the given $ref.
+	 * Sets this Example's reference property to the given string.
 	 *
-	 * @param String $ref
+	 * @param reference  a reference to an example object in the components in this OpenAPI document
 	 */
-	void set$ref(String $ref);
+	void setReference(String reference);
 
 	/**
-	 * sets this Example's $ref property to the given $ref and
-	 * returns this instance of Example
+	 * Sets this Example's reference property to the given string.
 	 *
-	 * @param String $ref
-	 * @return Example
+	 * @param reference  a reference to an example object in the components in this OpenAPI document
+	 * @return the current Example object
 	 */
-	Example $ref(String $ref);
+	Example reference(String reference);
 
 }
\ No newline at end of file
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 2fd4db669..b31756666 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
@@ -23,17 +23,21 @@
 
 /**
  * Content
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#contentObject"
+ * <p>
+ * A map to assist describing the media types for an operation's parameter or response.
+ * 
  */
 public interface Content extends Constructible, Map<String, MediaType> {
 
 	/**
-	 * Adds the MediaType for this Content, where name is the name of the MediaType and item is the MediaType itself
+	 * Adds the MediaType for this Content, where the key is the name of the
+	 * MediaType and the value is the object that describes the content passed into 
+	 * or returned from an operation.
 	 *
-	 * @param String name
-	 * @param MediaType item
-	 * @return Content
+	 * @param name  the name of a media type e.g. application/json.
+	 * @param item  an object that describes the content passed into or returned
+	 *            from an operation.
+	 * @return the current Content instance
 	 */
 	Content addMediaType(String name, MediaType item);
 
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
index 307b60062..0db6512f4 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
@@ -24,8 +24,35 @@
 /**
  * Tag
  * <p>
- * An object to store metadata to be available in the OpenAPI document.
- * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#tagObject">OpenAPI Specification Tag Object</a>
+ * An object to store metadata to be available in the OpenAPI document. 
+ * <p>
+ * Fixed Fields
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
+ * <tr>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
+ * </tr>
+ * <td>name</td>
+ * <td>string</td>
+ * <td>REQUIRED. The name of the tag.</td>
+ * </tr>
+ * <tr>
+ * <td>description</td>
+ * <td>string</td>
+ * <td>A short description for the tag. CommonMark syntax MAY be used for rich
+ * text representation.</td>
+ * </tr>
+ * <tr>
+ * <td>externalDocs</td>
+ * <td>{@link ExternalDocumentation External Documentation Object}</td>
+ * <td>Additional external documentation for this tag.</td>
+ * </tr>
+ * </table>
+ * 
+ * @see <a href=
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#tagObject">OpenAPI
+ *      Specification Tag Object</a>
  */
 public interface Tag extends Constructible, Extensible {
 

From d1a262ed3bcc3512aa6646699aa8048efab5010f Mon Sep 17 00:00:00 2001
From: Paul Gooderham <turkeyonmarblerye@gmail.com>
Date: Wed, 25 Oct 2017 16:15:49 -0400
Subject: [PATCH 16/23] Update the Javadocs and update some model objects. 8732

Signed-off-by: Paul Gooderham <turkeyonmarblerye@gmail.com>
---
 .../microprofile/openapi/models/PathItem.java | 422 +++++++-------
 .../openapi/models/headers/Header.java        | 345 ++++++++----
 .../openapi/models/links/Link.java            |   1 -
 .../openapi/models/parameters/Parameter.java  | 523 ++++++++++++------
 4 files changed, 769 insertions(+), 522 deletions(-)

diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
index 7641e992d..47a751f1e 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
@@ -26,99 +26,89 @@
 /**
  * PathItem
  * <p>
- * Describes the operations available on a single path. A Path Item MAY be
- * empty, due to ACL constraints. The path itself is still exposed to the
- * documentation viewer but they will not know which operations and parameters
+ * Describes the operations available on a single path. A Path Item MAY be empty
+ * due to ACL constraints. In that case the path itself is still exposed to the
+ * documentation viewer but you will not know which operations and parameters
  * are available.
  * <p>
  * Fixed Fields
- * <table border=1>
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
  * <tr>
- * <td>Field Name</td>
- * <td>Type</td>
- * <td>Description</td>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
  * </tr>
  * <tr>
- * <td>$ref</td>
+ * <td>reference</td>
  * <td>string</td>
  * <td>Allows for an external definition of this path item. The referenced
- * structure MUST be in the format of a Path Item Object. If there are conflicts
- * between the referenced definition and this Path Item's definition, the
- * behavior is undefined.</td>
+ * structure MUST be in the format of a Path Item Object. This field represents
+ * the $ref field in the OAS file. If there are conflicts between the referenced
+ * definition and this Path Item's definition, the behavior is undefined.</td>
  * </tr>
  * <tr>
  * <td>summary</td>
  * <td>string</td>
- * <td>An optional, string summary, intended to apply to all operations in this
- * path.</td>
+ * <td>A short summary of what the path item represents and which is intended to
+ * apply to all operations in this path.</td>
  * </tr>
  * <tr>
  * <td>description</td>
  * <td>string</td>
- * <td>An optional, string description, intended to apply to all operations in
- * this path. CommonMark syntax MAY be used for rich text representation.</td>
+ * <td>A detailed description of what the path item represents and which is
+ * intended to apply to all operations in this path. CommonMark syntax MAY be
+ * used for rich text representation.</td>
  * </tr>
  * <tr>
  * <td>get</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
- * Object</td>
+ * <td>{@link Operation Operation Object}</td>
  * <td>A definition of a GET operation on this path.</td>
  * </tr>
  * <tr>
  * <td>put</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
- * Object</td>
+ * <td>{@link Operation Operation Object}</td>
  * <td>A definition of a PUT operation on this path.</td>
  * </tr>
  * <tr>
  * <td>post</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
- * Object</td>
+ * <td>{@link Operation Operation Object}</td>
  * <td>A definition of a POST operation on this path.</td>
  * </tr>
  * <tr>
  * <td>delete</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
- * Object</td>
+ * <td>{@link Operation Operation Object}</td>
  * <td>A definition of a DELETE operation on this path.</td>
  * </tr>
  * <tr>
  * <td>options</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
- * Object</td>
+ * <td>{@link Operation Operation Object}</td>
  * <td>A definition of a OPTIONS operation on this path.</td>
  * </tr>
  * <tr>
  * <td>head</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
- * Object</td>
+ * <td>{@link Operation Operation Object}</td>
  * <td>A definition of a HEAD operation on this path.</td>
  * </tr>
  * <tr>
  * <td>patch</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
- * Object</td>
+ * <td>{@link Operation Operation Object}</td>
  * <td>A definition of a PATCH operation on this path.</td>
  * </tr>
  * <tr>
  * <td>trace</td>
- * <td>{@link org.eclipse.microprofile.openapi.models.Operation Operation}
- * Object</td>
+ * <td>{@link Operation Operation Object}</td>
  * <td>A definition of a TRACE operation on this path.</td>
  * </tr>
  * <tr>
  * <td>servers</td>
- * <td>[{@link org.eclipse.microprofile.openapi.models.servers.Server Server}
- * Object]</td>
+ * <td>[{@link Server Server Object}]</td>
  * <td>An alternative server array to service all operations in this path.</td>
  * </tr>
  * <tr>
  * <td>parameters</td>
- * <td>[{@link org.eclipse.microprofile.openapi.models.parameters.Parameter
- * Parameter} Object |
- * {@link org.eclipse.microprofile.openapi.models.parameters.Parameter
- * Reference} Object]</td>
- * <td>A list of parameters that are applicable for all the operations described
+ * <td>[{@link Parameter Parameter Object } | {@link Parameter Reference Object
+ * }]</td>
+ * <td>A list of parameters that are applicable to all the operations described
  * under this path. These parameters can be overridden at the operation level,
  * but cannot be removed there. The list MUST NOT include duplicated parameters.
  * A unique parameter is defined by a combination of a name and location. The
@@ -128,14 +118,14 @@
  * </table>
  * 
  * @see <a href=
- *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.md#pathItemObject">OpenAPI
- *      Specification Path Item Object</a>
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathItemObject">
+ *      OpenAPI Specification Path Item Object</a>
  */
 public interface PathItem extends Constructible, Extensible {
 
 	/**
-	 * All of the possible types of methods for this path
-	 */
+	 * All of the possible types of HTTP operations for this path
+	 **/
 	enum HttpMethod {
 	    POST,
 	    GET,
@@ -148,345 +138,319 @@ enum HttpMethod {
 	}
 
 	/**
-	 * returns the summary property from a PathItem instance.
+	 * Returns the summary property from a PathItem instance.
 	 *
-	 * @return String summary
+	 * @return a short summary of what the path item represents
 	 **/
-
 	String getSummary();
 
 	/**
-	 * sets this PathItem's summary property to the given summary.
+	 * Sets this PathItem's summary property to the given string.
 	 *
-	 * @param String summary
-	 */
+	 * @param summary  short summary of what the path item represents
+	 **/
 	void setSummary(String summary);
 
 	/**
-	* sets this PathItem's summary property to the given summary and
-	* returns this instance of PathItem
-	*
-	* @param String summary
-	* @return PathItem
-	*/
+	 * Sets this PathItem's summary property to the given string.
+	 *
+	 * @param summary  short summary of what the path item represents
+	 * @return the current PathItem instance
+	 **/
 	PathItem summary(String summary);
 
 	/**
-	 * returns the description property from a PathItem instance.
+	 * Returns the description property from a PathItem instance.
 	 *
-	 * @return String description
+	 * @return a detailed description of what the path item represents
 	 **/
-
 	String getDescription();
 
 	/**
-	 * sets this PathItem's description property to the given description.
+	 * Sets this PathItem's description property to the given string.
 	 *
-	 * @param String description
-	 */
+	 * @param description  detailed description of what the path item represents
+	 **/
 	void setDescription(String description);
 
 	/**
-	* sets this PathItem's description property to the given description and
-	* returns this instance of PathItem
-	*
-	* @param String description
-	* @return PathItem
-	*/
+	 * Sets this PathItem's description property to the given string.
+	 *
+	 * @param description  detailed description of what the path item represents
+	 * @return the current PathItem instance
+	 **/
 	PathItem description(String description);
 
 	/**
-	 * returns the get property from a PathItem instance.
+	 * Returns the get property from a PathItem instance.
 	 *
-	 * @return Operation get
+	 * @return definition of a GET operation on this path
 	 **/
-	Operation getGet();
+	Operation getGetOperation();
 
 	/**
-	 * sets this PathItem's get property to the given get.
+	 * Sets this PathItem's get property to the given operation.
 	 *
-	 * @param Operation get
-	 */
-	void setGet(Operation get);
+	 * @param get  definition of a GET operation
+	 **/
+	void setGetOperation(Operation get);
 
 	/**
-	* sets this PathItem's get property to the given get and
-	* returns this instance of PathItem
-	*
-	* @param Operation get
-	* @return PathItem
-	*/
+	 * Sets this PathItem's get property to the given operation.
+	 *
+	 * @param get  definition of a GET operation
+	 * @return the current PathItem instance
+	 **/
 	PathItem get(Operation get);
 
 	/**
-	 * returns the put property from a PathItem instance.
+	 * Returns the put property from a PathItem instance.
 	 *
-	 * @return Operation put
+	 * @return definition of a PUT operation on this path
 	 **/
-
-	Operation getPut();
+	Operation getPutOperation();
 
 	/**
-	 * sets this PathItem's put property to the given put.
+	 * Sets this PathItem's put property to the given operation.
 	 *
-	 * @param Operation put
-	 */
-	void setPut(Operation put);
+	 * @param put  definition of a PUT operation
+	 **/
+	void setPutOperation(Operation put);
 
 	/**
-	* sets this PathItem's put property to the given put and
-	* returns this instance of PathItem
-	*
-	* @param Operation put
-	* @return PathItem
-	*/
+	 * Sets this PathItem's put property to the given operation.
+	 *
+	 * @param put  definition of a PUT operation
+	 * @return the current PathItem instance
+	 **/
 	PathItem put(Operation put);
 
 	/**
-	 * returns the post property from a PathItem instance.
+	 * Returns the post property from a PathItem instance.
 	 *
-	 * @return Operation post
+	 * @return definition of a POST operation on this path
 	 **/
-
-	Operation getPost();
+	Operation getPostOperation();
 
 	/**
-	 * sets this PathItem's post property to the given post.
+	 * Sets this PathItem's post property to the given operation.
 	 *
-	 * @param Operation post
-	 */
-	void setPost(Operation post);
+	 * @param post  definition of a PUT operation
+	 **/
+	void setPostOperation(Operation post);
 
 	/**
-	* sets this PathItem's post property to the given post and
-	* returns this instance of PathItem
-	*
-	* @param Operation post
-	* @return PathItem
-	*/
+	 * Sets this PathItem's post property to the given operation.
+	 *
+	 * @param post  definition of a PUT operation
+	 * @return the current PathItem instance
+	 **/
 	PathItem post(Operation post);
 
 	/**
-	 * returns the delete property from a PathItem instance.
+	 * Returns the delete property from a PathItem instance.
 	 *
-	 * @return Operation delete
+	 * @return definition of a DELETE operation on this path
 	 **/
-
-	Operation getDelete();
+	Operation getDeleteOperation();
 
 	/**
-	 * sets this PathItem's delete property to the given delete.
+	 * Sets this PathItem's delete property to the given operation.
 	 *
-	 * @param Operation delete
-	 */
-	void setDelete(Operation delete);
+	 * @param delete  definition of a DELETE operation
+	 **/
+	void setDeleteOperation(Operation delete);
 
 	/**
-	* sets this PathItem's delete property to the given delete and
-	* returns this instance of PathItem
-	*
-	* @param Operation delete
-	* @return PathItem
-	*/
+	 * Sets this PathItem's delete property to the given operation.
+	 *
+	 * @param delete  definition of a DELETE operation
+	 * @return the current PathItem instance
+	 **/
 	PathItem delete(Operation delete);
 
 	/**
-	 * returns the options property from a PathItem instance.
+	 * Returns the options property from a PathItem instance.
 	 *
-	 * @return Operation options
+	 * @return definition of an OPTIONS operation on this path
 	 **/
-
-	Operation getOptions();
+	Operation getOptionsOperation();
 
 	/**
-	 * sets this PathItem's options property to the given options.
+	 * Sets this PathItem's options property to the given operation.
 	 *
-	 * @param Operation options
-	 */
-	void setOptions(Operation options);
+	 * @param options  definition of an OPTIONS operation
+	 **/
+	void setOptionsOperation(Operation options);
 
 	/**
-	* sets this PathItem's options property to the given options and
-	* returns this instance of PathItem
-	*
-	* @param Operation options
-	* @return PathItem
-	*/
+	 * Sets this PathItem's options property to the given operation.
+	 *
+	 * @param options  definition of an OPTIONS operation
+	 * @return the current PathItem instance
+	 **/
 	PathItem options(Operation options);
 
 	/**
-	 * returns the head property from a PathItem instance.
+	 * Returns the head property from a PathItem instance.
 	 *
-	 * @return Operation head
+	 * @return definition of a HEAD operation on this path
 	 **/
-
-	Operation getHead();
+	Operation getHeadOperation();
 
 	/**
-	 * sets this PathItem's head property to the given head.
+	 * Sets this PathItem's head property to the given operation.
 	 *
-	 * @param Operation head
-	 */
-	void setHead(Operation head);
+	 * @param head  definition of a HEAD operation
+	 **/
+	void setHeadOperation(Operation head);
 
 	/**
-	* sets this PathItem's head property to the given head and
-	* returns this instance of PathItem
-	*
-	* @param Operation head
-	* @return PathItem
-	*/
+	 * Sets this PathItem's head property to the given operation.
+	 *
+	 * @param head  definition of a HEAD operation
+	 * @return the current PathItem instance
+	 **/
 	PathItem head(Operation head);
 
 	/**
-	 * returns the patch property from a PathItem instance.
+	 * Returns the patch property from a PathItem instance.
 	 *
-	 * @return Operation patch
+	 * @return definition of a PATCH operation on this path
 	 **/
-
-	Operation getPatch();
+	Operation getPatchOperation();
 
 	/**
-	 * sets this PathItem's patch property to the given patch.
+	 * Sets this PathItem's patch property to the given operation.
 	 *
-	 * @param Operation patch
-	 */
-	void setPatch(Operation patch);
+	 * @param patch  definition of a PATCH operation
+	 **/
+	void setPatchOperation(Operation patch);
 
 	/**
-	* sets this PathItem's patch property to the given patch and
-	* returns this instance of PathItem
-	*
-	* @param Operation patch
-	* @return PathItem
-	*/
+	 * Sets this PathItem's patch property to the given operation.
+	 *
+	 * @param patch  definition of a PATCH operation
+	 * @return the current PathItem instance
+	 **/
 	PathItem patch(Operation patch);
 
 	/**
-	 * returns the trace property from a PathItem instance.
+	 * Returns the trace property from a PathItem instance.
 	 *
-	 * @return Operation trace
+	 * @return definition of a TRACE operation on this path
 	 **/
-
-	Operation getTrace();
+	Operation getTraceOperation();
 
 	/**
-	 * sets this PathItem's trace property to the given trace.
+	 * Sets this PathItem's trace property to the given operation.
 	 *
-	 * @param Operation trace
-	 */
-	void setTrace(Operation trace);
+	 * @param trace  definition of a TRACE operation
+	 **/
+	void setTraceOperation(Operation trace);
 
 	/**
-	* sets this PathItem's trace property to the given trace and
-	* returns this instance of PathItem
-	*
-	* @param Operation trace
-	* @return PathItem
-	*/
+	 * Sets this PathItem's trace property to the given operation.
+	 *
+	 * @param trace  definition of a TRACE operation
+	 * @return the current PathItem instance
+	 **/
 	PathItem trace(Operation trace);
 
 	/**
-	 * Returns a list of all the operation for this path.
+	 * Returns a list of all the operations for this path item.
 	 * 
-	 * @return List&lt;Operation&gt; allOperations
-	 */
+	 * @return a list of all the operations for this path item
+	 **/
 	List<Operation> readOperations();
 
 	/**
-	 * Returns a map with all the operations for this path, where the HttpMethods are keys.
+	 * Returns a map with all the operations for this path where the keys are HttpMethods.
 	 * 
-	 * @return Map&lt;HttpMethod, Operation&gt; result
-	 */
+	 * @return a map with all the operations for this path where the keys are HttpMethods
+	 **/
 	Map<PathItem.HttpMethod, Operation> readOperationsMap();
 
 	/**
-	 * returns the servers property from a PathItem instance.
+	 * Returns the servers property from a PathItem instance.
 	 *
-	 * @return List&lt;Server&gt; servers
+	 * @return a list of all the servers defined in this path item
 	 **/
-
 	List<Server> getServers();
 
 	/**
-	 * sets this PathItem's servers property to the given servers.
+	 * Sets this PathItem's servers property to the given list.
 	 *
-	 * @param List&lt;Server&gt; servers
-	 */
+	 * @param servers  a list of the servers to service operations in this path item
+	 **/
 	void setServers(List<Server> servers);
 
 	/**
-	* sets this PathItem's patch servers to the given servers and
-	* returns this instance of PathItem
-	*
-	* @param List&lt;Server&gt; servers
-	* @return PathItem
-	*/
+	 * Sets this PathItem's servers property to the given list.
+	 *
+	 * @param servers  a list of the servers to service operations in this path item
+	 * @return the current PathItem instance
+	 **/
 	PathItem servers(List<Server> servers);
 
 	/**
-	 * Adds the given serversItem to this PathItem's list of serversItem, with the given key as its key.
+	 * Adds the given server to this PathItem's list of servers.
 	 *
-	 * @param String key
-	 * @param Server serversItem
-	 * @return PathItem
-	*/
+	 * @param serversItem a server to service operations in this path item
+	 * @return the current PathItem instance
+	 **/
 	PathItem addServersItem(Server serversItem);
 
 	/**
-	 * returns the parameters property from a PathItem instance.
+	 * Returns the parameters property from this PathItem instance.
 	 *
-	 * @return List&lt;Parameter&gt; parameters
+	 * @return a list of parameters that are applicable to all the operations described under this path
 	 **/
-
 	List<Parameter> getParameters();
 
 	/**
-	 * sets this PathItem's parameters property to the given parameters.
+	 * Sets this PathItem's parameters property to the given list.
 	 *
-	 * @param List&lt;Parameter&gt; servers
-	 */
+	 * @param parameters  a list of parameters that are applicable to all the operations described under this path
+	 **/
 	void setParameters(List<Parameter> parameters);
 
 	/**
-	 * sets this PathItem's patch parameters to the given parameters and
-	 * returns this instance of PathItem
+	 * Sets this PathItem's parameters property to the given list.
 	 *
-	 * @param List&lt;Parameter&gt; servers
-	 * @return PathItem
-	 */
+	 * @param parameters  a list of parameters that are applicable to all the operations described under this path
+	 * @return the current PathItem instance
+	 **/
 	PathItem parameters(List<Parameter> parameters);
 
 	/**
-	 * Adds the given parametersItem to this PathItem's list of parametersItem, with the given key as its key.
+	 * Adds the given parameter to this PathItem's list of parameters.
 	 *
-	 * @param String key
-	 * @param Parameter parametersItem
-	 * @return PathItem
-	*/
+	 * @param parametersItem  a parameter that is applicable to all the operations described under this path
+	 * @return the current PathItem instance
+	 **/
 	PathItem addParametersItem(Parameter parametersItem);
 
 	/**
-	 * returns the ref property from a PathItem instance.
+	 * Returns the reference property from this PathItem instance.
 	 *
-	 * @return String ref
+	 * @return a reference to a path object in the components in this OpenAPI document
 	 **/
-	String get$ref();
+	String getReference();
 
 	/**
-	 * sets this PathItem's $ref property to the given $ref.
+	 * Sets this PathItem's reference property to the given string.
 	 *
-	 * @param String $ref
-	 */
-	void set$ref(String $ref);
+	 * @param reference  a reference to a path object in the components in this OpenAPI document
+	 **/
+	void setReference(String reference);
 
 	/**
-	 * sets this PathItem's $ref parameters to the given $ref and
-	 * returns this instance of PathItem
+	 * Sets this PathItem's reference property to the given string.
 	 *
-	 * @param List&lt;String&gt; $ref
-	 * @return PathItem
-	 */
-	PathItem $ref(String $ref);
+	 * @param reference  a reference to a path object in the components in this OpenAPI document
+	 * @return the current PathItem instance
+	 **/
+	PathItem reference(String reference);
 
 }
\ No newline at end of file
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 dc1947bc8..f8942c2b1 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
@@ -25,10 +25,151 @@
 import org.eclipse.microprofile.openapi.models.media.Content;
 import org.eclipse.microprofile.openapi.models.media.Schema;
 
+/**
+ * Header
+ * <p>
+ * Describes a single operation header parameter.
+ * <p>
+ * Fixed Fields
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
+ * <tr>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td>reference</td>
+ * <td>string</td>
+ * <td>Allows for an external definition of this header. The referenced
+ * structure MUST be in the format of a Header Object. This field represents the
+ * $ref field in the OAS file. If there are conflicts between the referenced
+ * definition and this Header's definition, the behavior is undefined.</td>
+ * </tr>
+ * <tr>
+ * <td>description</td>
+ * <td>string</td>
+ * <td>A brief description of the parameter. This could contain examples of use.
+ * CommonMark syntax MAY be used for rich text representation.</td>
+ * </tr>
+ * <tr>
+ * <td>required</td>
+ * <td>boolean</td>
+ * <td>Determines whether this parameter is mandatory. The property MAY be
+ * included and its default value is false.</td>
+ * </tr>
+ * <tr>
+ * <td>deprecated</td>
+ * <td>boolean</td>
+ * <td>Specifies that a parameter is deprecated and SHOULD be transitioned out
+ * of usage.</td>
+ * </tr>
+ * <tr>
+ * <td>allowEmptyValue</td>
+ * <td>boolean</td>
+ * <td>Sets the ability to pass empty-valued parameters. This is valid only for
+ * query parameters and allows sending a parameter with an empty value. Default
+ * value is false. If style is used, and if behavior is n/a (cannot be
+ * serialized), the value of allowEmptyValue SHALL be ignored.</td>
+ * </tr>
+ * </table>
+ * The rules for serialization of the header parameter are specified in one of
+ * two ways. For simpler scenarios, a schema and style can describe the
+ * structure and syntax of the header parameter.
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
+ * <tr>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td>style</td>
+ * <td>string</td>
+ * <td>Describes how the parameter value will be serialized depending on the
+ * type of the parameter value. Default value for header is simple.</td>
+ * </tr>
+ * <tr>
+ * <td>explode</td>
+ * <td>boolean</td>
+ * <td>When this is true, parameter 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 parameters this property has no effect. When style is
+ * form, the default value is true. For all other styles, the default value is
+ * false.</td>
+ * </tr>
+ * <tr>
+ * <td>allowReserved</td>
+ * <td>boolean</td>
+ * <td>Determines whether the parameter value SHOULD allow reserved characters,
+ * as defined by RFC3986 <code>:/?#[]@!$&'()*+,;=</code> to be included without
+ * percent-encoding. This property only applies to parameters with an in value
+ * of query. The default value is false.</td>
+ * </tr>
+ * <tr>
+ * <td>schema</td>
+ * <td>{@link Schema Schema Object} | {@link Schema Reference Object}</td>
+ * <td>The schema defining the type used for the parameter.</td>
+ * </tr>
+ * <tr>
+ * <td>example</td>
+ * <td>Any</td>
+ * <td>Example of the media type. The example SHOULD match the specified schema
+ * and encoding properties if present. The example object is mutually exclusive
+ * of the examples object. Furthermore, if referencing a schema which contains
+ * an example, the example value SHALL override the example provided by the
+ * schema. To represent examples of media types that cannot naturally be
+ * represented in JSON or YAML, a string value can contain the example with
+ * escaping where necessary.</td>
+ * </tr>
+ * <tr>
+ * <td>examples</td>
+ * <td>Map[ string, {@link Example Example Object} | {@link Example Reference Object}]</td>
+ * <td>Examples of the media type. Each example SHOULD contain a value in the
+ * correct format as specified in the parameter encoding. The examples object is
+ * mutually exclusive of the example object. Furthermore, if referencing a
+ * schema which contains an example, the examples value SHALL override the
+ * example provided by the schema.</td>
+ * </tr>
+ * </table>
+ * For more complex scenarios, the content property can define the media type
+ * and schema of the parameter. A parameter MUST contain either a schema
+ * property, or a content property, but not both. When example or examples are
+ * provided in conjunction with the schema object, the example MUST follow the
+ * prescribed serialization strategy for the parameter.
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
+ * <tr>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td>content</td>
+ * <td>Map[string, {@link MediaType Media Type Object} ]</td>
+ * <td>A map containing the representations for the parameter. The key is the
+ * media type and the value describes it. The map MUST only contain one
+ * entry.</td>
+ * </tr>
+ * </table>
+ * Style Values
+ * <p>
+ * For headers only one way of serializing the parameters, simple.
+ * <table border=1 cellpadding="8">
+ * <tr>
+ * <th>Style</th>
+ * <th>Type</th>
+ * <th>Comments</th>
+ * </tr>
+ * <tr>
+ * <td>simple</td>
+ * <td>array</td>
+ * <td>Simple style parameters defined by RFC6570. This option replaces
+ * collectionFormat with a csv value from OpenAPI 2.0.</td>
+ * </tr>
+ * </table>
+ */
 public interface Header extends Constructible, Extensible {
 	
     /**
-     * Gets or Sets style
+     * Controls the style of serialization. Only one style is supported for headers.
      */
     public enum StyleEnum {
         SIMPLE("simple");
@@ -46,279 +187,257 @@ public String toString() {
     }
 
 	/**
-	 * returns the description property from a Header instance.
+	 * Returns the description property from a Header instance.
 	 *
-	 * @return String description
+	 * @return a brief description of the header parameter.
 	 **/
-
 	String getDescription();
 
 	/**
-	 * sets this Header's description property to the given description.
+	 * Sets this Header's description property to the given string.
 	 *
-	 * @param String description
+	 * @param description  a brief description of the header parameter
 	 */
 	void setDescription(String description);
 
 	/**
-	 * sets this Header's description property to the given description and
-	 * returns this instance of Header
+	 * Sets this Header's description property to the given string.
 	 *
-	 * @param String description
-	 * @return Header
+	 * @param description  a brief description of the header parameter
+	 * @return the current Header instance
 	 */
 	Header description(String description);
 
 	/**
-	 * returns the required property from a Header instance.
+	 * Returns the required property from a Header instance.
 	 *
-	 * @return Boolean required
+	 * @return whether this parameter is mandatory
 	 **/
-
 	Boolean getRequired();
 
 	/**
-	 * sets this Header's required property to the given required.
+	 * Sets this Header's required property to the given value.
 	 *
-	 * @param Boolean required
+	 * @param required  whether this parameter is mandatory
 	 */
 	void setRequired(Boolean required);
 
 	/**
-	 * sets this Header's required property to the given required and
-	 * returns this instance of Header
+	 * Sets this Header's required property to the given value.
 	 *
-	 * @param Boolean required
-	 * @return Header
+	 * @param required  whether this parameter is mandatory
+	 * @return the current Header instance
 	 */
 	Header required(Boolean required);
 
 	/**
-	 * returns the deprecated property from a Header instance.
+	 * Returns the deprecated property from a Header instance.
 	 *
-	 * @return Boolean deprecated
+	 * @return  whether a parameter is deprecated
 	 **/
-
 	Boolean getDeprecated();
 
 	/**
-	 * sets this Header's deprecated property to the given deprecated.
+	 * Sets this Header's deprecated property to the given value.
 	 *
-	 * @param Boolean deprecated
+	 * @param deprecated  whether a parameter is deprecated
 	 */
 	void setDeprecated(Boolean deprecated);
 
 	/**
-	 * sets this Header's deprecated property to the given deprecated and
-	 * returns this instance of Header
+	 * Sets this Header's deprecated property to the given value.
 	 *
-	 * @param Boolean deprecated
-	 * @return Header
+	 * @param deprecated  whether a parameter is deprecated
+	 * @return the current Header instance
 	 */
 	Header deprecated(Boolean deprecated);
 
 	/**
-	 * returns the allowEmptyValue property from a Header instance.
+	 * Returns the allowEmptyValue property from a Header instance.
 	 *
-	 * @return Boolean allowEmptyValue
+	 * @return the ability to pass empty-valued parameters
 	 **/
-
 	Boolean getAllowEmptyValue();
 
 	/**
-	 * sets this Header's allowEmptyValue property to the given allowEmptyValue.
+	 * Sets this Header's allowEmptyValue property to the given value.
 	 *
-	 * @param Boolean allowEmptyValue
+	 * @param allowEmptyValue  the ability to pass empty-valued parameters
 	 */
 	void setAllowEmptyValue(Boolean allowEmptyValue);
 
 	/**
-	 * sets this Header's allowEmptyValue property to the given allowEmptyValue and
-	 * returns this instance of Header
+	 * Sets this Header's allowEmptyValue property to the given value.
 	 *
-	 * @param Boolean allowEmptyValue
-	 * @return Header
+	 * @param allowEmptyValue  the ability to pass empty-valued parameters
+	 * @return the current Header instance
 	 */
 	Header allowEmptyValue(Boolean allowEmptyValue);
 
 	/**
-	 * returns the style property from a Header instance.
+	 * Returns the style property from a Header instance.
 	 *
-	 * @return StyleEnum style
+	 * @return  how the parameter value will be serialized
 	 **/
-
 	StyleEnum getStyle();
 
 	/**
-	 * sets this Header's style property to the given style.
+	 * Sets this Header's style property to the given style.
 	 *
-	 * @param StyleEnum style
+	 * @param style  how the parameter value will be serialized
 	 */
 	void setStyle(StyleEnum style);
 
 	/**
-	 * sets this Header's style property to the given style and
-	 * returns this instance of Header
+	 * Sets this Header's style property to the given style.
 	 *
-	 * @param StyleEnum style
-	 * @return Header
+	 * @param style  how the parameter value will be serialized
+	 * @return the current Header instance
 	 */
 	Header style(StyleEnum style);
 
 	/**
-	 * returns the explode property from a Header instance.
+	 * Returns the explode property from a Header instance.
 	 *
-	 * @return Boolean explode
+	 * @return whether parameter values of type "array" or "object" generate separate parameters for each value
 	 **/
-
 	Boolean getExplode();
 
 	/**
-	 * sets this Header's explode property to the given explode.
+	 * Sets this Header's explode property to the given value.
 	 *
-	 * @param Boolean allowEmptyValue
+	 * @param explode  whether parameter values of type "array" or "object" generate separate parameters for each value
 	 */
 	void setExplode(Boolean explode);
 
 	/**
-	 * sets this Header's explode property to the given explode and
-	 * returns this instance of Header
+	 * Sets this Header's explode property to the given value.
 	 *
-	 * @param Boolean explode
-	 * @return Header
+	 * @param explode  whether parameter values of type "array" or "object" generate separate parameters for each value
+	 * @return the current Header instance
 	 */
 	Header explode(Boolean explode);
 
 	/**
-	 * returns the schema property from a Header instance.
+	 * Returns the schema property from a Header instance.
 	 *
-	 * @return Schema schema
+	 * @return schema defining the type used for the parameter
 	 **/
-
 	Schema getSchema();
 
 	/**
-	 * sets this Header's schema property to the given schema.
+	 * Sets this Header's schema property to the given object.
 	 *
-	 * @param Schema schema
+	 * @param schema  schema defining the type used for the parameter
 	 */
 	void setSchema(Schema schema);
 
 	/**
-	 * sets this Header's schema property to the given schema and
-	 * returns this instance of Header
+	 * Sets this Header's schema property to the given object.
 	 *
-	 * @param Schema schema
-	 * @return Header
+	 * @param schema  schema defining the type used for the parameter
+	 * @return the current Header instance
 	 */
 	Header schema(Schema schema);
 
 	/**
-	 * returns the examples property from a Header instance.
+	 * Returns the examples property from a Header instance.
 	 *
-	 * @return Map&lt;String, Example&gt; examples
+	 * @return examples of the media type
 	 **/
-
 	Map<String, Example> getExamples();
 
 	/**
-	 * Sets the examples map of header instance to parameter.
+	 * Sets the examples property of this Header instance to the given map.
 	 *
-	 * @param examples
+	 * @param examples  examples of the media type
 	 */
-
 	void setExamples(Map<String, Example> examples);
 
 	/**
-	 * Sets the examples map of header instance
-	 * to parameter and returns the instance.
+	 * Sets the examples property of this Header instance to the given map.
 	 *
-	 * @param examples
-	 * @return Header instance with set examples map.
+	 * @param examples  examples of the media type
+	 * @return the current Header instance 
 	 */
-
 	Header examples(Map<String, Example> examples);
 
 	/**
-	 * Adds a key-value item to examples map
-	 * of header instance and returns the instance.
+	 * Adds an example of the media type using the specified key.
 	 *
-	 * @param key
-	 * @param examplesItem
-	 * @return Header instance with a key-value pair added to examples map
+	 * @param key string to represent the example
+	 * @param examplesItem  example of the media type
+	 * @return the current Header instance
 	 */
-
 	Header addExample(String key, Example examplesItem);
 
 	/**
-	 * returns the example property from a Header instance.
+	 * Returns the example property from a Header instance.
 	 *
-	 * @return String example
+	 * @return example of the media type
 	 **/
-
-	String getExample();
+	Object getExample();
 
 	/**
-	 * sets this Header's example property to the given example.
+	 * Sets this Header's example property to the given object.
 	 *
-	 * @param String example
+	 * @param example  example of the media type
 	 */
-	void setExample(String example);
+	void setExample(Object example);
 
 	/**
-	 * sets this Header's example property to the given example and
-	 * returns this instance of Header
+	 * Sets this Header's example property to the given object.
 	 *
-	 * @param String example
-	 * @return Header
+	 * @param example  example of the media type
+	 * @return the current Header instance
 	 */
-	Header example(String example);
+	Header example(Object example);
 
 	/**
-	 * returns the content property from a Header instance.
+	 * Returns the content property from a Header instance.
 	 *
-	 * @return Content content
+	 * @return a map containing the media representations for the parameter
 	 **/
-
 	Content getContent();
 
 	/**
-	 * sets this Header's content property to the given content.
+	 * Sets this Header's content property to the given object.
 	 *
-	 * @param Content content
+	 * @param content  a map containing the media representations for the parameter
 	 */
 	void setContent(Content content);
 
 	/**
-	 * sets this Header's content property to the given content and
-	 * returns this instance of Header
+	 * Sets this Header's content property to the given object.
 	 *
-	 * @param Content content
-	 * @return Header
+	 * @param content  a map containing the media representations for the parameter
+	 * @return the current Header instance
 	 */
 	Header content(Content content);
 
 	/**
-	 * returns the $ref property from a Header instance.
+	 * Returns the reference property from a Header instance.
 	 *
-	 * @return String $ref
+	 * @return a reference to a header object in an OpenAPI document especially
+	 *         in the components in this OpenAPI document
 	 */
-	String get$ref();
+	String getReference();
 
 	/**
-	 * sets this Header's $ref property to the given $ref.
+	 * Sets this Header's reference property to the given string.
 	 *
-	 * @param String $ref
+	 * @param reference  a reference to a header object in an OpenAPI document
+	 *            especially in the components in this OpenAPI document
 	 */
-	void set$ref(String $ref);
+	void setReference(String reference);
 
 	/**
-	 * sets this Header's $ref property to the given $ref and
-	 * returns this instance of Header
+	 * Sets this Header's reference property to the given string.
 	 *
-	 * @param String $ref
-	 * @return Header
+	 * @param reference  a reference to a header object in an OpenAPI document
+	 *            especially in the components in this OpenAPI document
+	 * @return the current Header instance
 	 */
-	Header $ref(String $ref);
+	Header reference(String reference);
 
 }
\ No newline at end of file
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 a80dff035..8ef6e9b22 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
@@ -21,7 +21,6 @@
 
 import org.eclipse.microprofile.openapi.models.Constructible;
 import org.eclipse.microprofile.openapi.models.Extensible;
-import org.eclipse.microprofile.openapi.models.headers.Header;
 import org.eclipse.microprofile.openapi.models.parameters.RequestBody;
 import org.eclipse.microprofile.openapi.models.servers.Server;
 
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 355a28d6e..03fb708cf 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
@@ -21,18 +21,242 @@
 
 import org.eclipse.microprofile.openapi.models.Extensible;
 import org.eclipse.microprofile.openapi.models.examples.Example;
+import org.eclipse.microprofile.openapi.models.media.MediaType;
 import org.eclipse.microprofile.openapi.models.media.Content;
 import org.eclipse.microprofile.openapi.models.media.Schema;
 
 /**
  * Parameter
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#parameterObject"
+ * <p>
+ * Describes a single operation parameter.
+ * <p>
+ * A unique parameter is defined by a combination of a name and location.
+ * <p>
+ * Parameter Locations
+ * <p>
+ * There are four possible parameter locations specified by the in field:
+ * <ul>
+ * <li>path - Used together with Path Templating, where the parameter value is
+ * actually part of the operation's URL. This does not include the host or base
+ * path of the API. For example, in /items/{itemId}, the path parameter is
+ * itemId.</li>
+ * <li>query - Parameters that are appended to the URL. For example, in
+ * /items?id=###, the query parameter is id.</li>
+ * <li>header - Custom headers that are expected as part of the request. Note
+ * that RFC7230 states header names are case insensitive.</li>
+ * <li>cookie - Used to pass a specific cookie value to the API.</li>
+ * </ul>
+ * <p>
+ * Fixed Fields
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
+ * <tr>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td>reference</td>
+ * <td>string</td>
+ * <td>Allows for an external definition of this parameter. The referenced
+ * structure MUST be in the format of a Parameter Object. This field represents
+ * the $ref field in the OAS file. If there are conflicts between the referenced
+ * definition and this Parameter's definition, the behavior is undefined.</td>
+ * </tr>
+ * <tr>
+ * <td>name</td>
+ * <td>string</td>
+ * <td>REQUIRED. The name of the parameter. Parameter names are case sensitive.
+ * <ul>
+ * <li>If in is "path", the name field MUST correspond to the associated path
+ * segment from the path field in the Paths Object. See Path Templating for
+ * further information.</li>
+ * <li>If in is "header" and the name field is "Accept", "Content-Type" or
+ * "Authorization", the parameter definition SHALL be ignored.</li>
+ * <li>For all other cases, the name corresponds to the parameter name used by
+ * the in property.</li></ul></td>
+ * </tr>
+ * <tr>
+ * <td>in</td>
+ * <td>string</td>
+ * <td>REQUIRED. The location of the parameter. Possible values are "query",
+ * "header", "path" or "cookie".</td>
+ * </tr>
+ * <tr>
+ * <td>description</td>
+ * <td>string</td>
+ * <td>A brief description of the parameter. This could contain examples of use.
+ * CommonMark syntax MAY be used for rich text representation.</td>
+ * </tr>
+ * <tr>
+ * <td>required</td>
+ * <td>boolean</td>
+ * <td>Determines whether this parameter is mandatory. If the parameter location
+ * is "path", this property is REQUIRED and its value MUST be true. Otherwise,
+ * the property MAY be included and its default value is false.</td>
+ * </tr>
+ * <tr>
+ * <td>deprecated</td>
+ * <td>boolean</td>
+ * <td>Specifies that a parameter is deprecated and SHOULD be transitioned out
+ * of usage.</td>
+ * </tr>
+ * <tr>
+ * <td>allowEmptyValue</td>
+ * <td>boolean</td>
+ * <td>Sets the ability to pass empty-valued parameters. This is valid only for
+ * query parameters and allows sending a parameter with an empty value. Default
+ * value is false. If style is used, and if behavior is n/a (cannot be
+ * serialized), the value of allowEmptyValue SHALL be ignored.</td>
+ * </tr>
+ * </table>
+ * The rules for serialization of the parameter are specified in one of two
+ * ways. For simpler scenarios, a schema and style can describe the structure
+ * and syntax of the parameter.
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
+ * <tr>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td>style</td>
+ * <td>string</td>
+ * <td>Describes how the parameter value will be serialized depending on the
+ * type of the parameter value. Default values (based on value of in): for query
+ * - form; for path - simple; for header - simple; for cookie - form.</td>
+ * </tr>
+ * <tr>
+ * <td>explode</td>
+ * <td>boolean</td>
+ * <td>When this is true, parameter 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 parameters this property has no effect. When style is
+ * form, the default value is true. For all other styles, the default value is
+ * false.</td>
+ * </tr>
+ * <tr>
+ * <td>allowReserved</td>
+ * <td>boolean</td>
+ * <td>Determines whether the parameter value SHOULD allow reserved characters,
+ * as defined by RFC3986 <code>:/?#[]@!$&'()*+,;=</code> to be included without
+ * percent-encoding. This property only applies to parameters with an in value
+ * of query. The default value is false.</td>
+ * </tr>
+ * <tr>
+ * <td>schema</td>
+ * <td>{@link Schema Schema Object} | {@link Schema Reference Object}</td>
+ * <td>The schema defining the type used for the parameter.</td>
+ * </tr>
+ * <tr>
+ * <td>example</td>
+ * <td>Any</td>
+ * <td>Example of the media type. The example SHOULD match the specified schema
+ * and encoding properties if present. The example object is mutually exclusive
+ * of the examples object. Furthermore, if referencing a schema which contains
+ * an example, the example value SHALL override the example provided by the
+ * schema. To represent examples of media types that cannot naturally be
+ * represented in JSON or YAML, a string value can contain the example with
+ * escaping where necessary.</td>
+ * </tr>
+ * <tr>
+ * <td>examples</td>
+ * <td>Map[ string, {@link Example Example Object} | {@link Example Reference
+ * Object}]</td>
+ * <td>Examples of the media type. Each example SHOULD contain a value in the
+ * correct format as specified in the parameter encoding. The examples object is
+ * mutually exclusive of the example object. Furthermore, if referencing a
+ * schema which contains an example, the examples value SHALL override the
+ * example provided by the schema.</td>
+ * </tr>
+ * </table>
+ * For more complex scenarios, the content property can define the media type
+ * and schema of the parameter. A parameter MUST contain either a schema
+ * property, or a content property, but not both. When example or examples are
+ * provided in conjunction with the schema object, the example MUST follow the
+ * prescribed serialization strategy for the parameter.
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
+ * <tr>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td>content</td>
+ * <td>Map[string, {@link MediaType Media Type Object} ]</td>
+ * <td>A map containing the representations for the parameter. The key is the
+ * media type and the value describes it. The map MUST only contain one
+ * entry.</td>
+ * </tr>
+ * </table>
+ * Style Values
+ * <p>
+ * In order to support common ways of serializing simple parameters, a set of
+ * style values are defined.
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
+ * <tr>
+ * <th>Style</th>
+ * <th>Type</th>
+ * <th>In</th>
+ * <th>Comments</th>
+ * </tr>
+ * <tr>
+ * <td>matrix</td>
+ * <td>primitive, array, object</td>
+ * <td>path</td>
+ * <td>Path-style parameters defined by RFC6570</td>
+ * </tr>
+ * <tr>
+ * <td>label</td>
+ * <td>primitive, array, object</td>
+ * <td>path</td>
+ * <td>Label style parameters defined by RFC6570</td>
+ * </tr>
+ * <tr>
+ * <td>form</td>
+ * <td>primitive, array, object</td>
+ * <td>query, cookie</td>
+ * <td>Form style parameters defined by RFC6570. This option replaces
+ * collectionFormat with a csv (when explode is false) or multi (when explode is
+ * true) value from OpenAPI 2.0.</td>
+ * </tr>
+ * <tr>
+ * <td>simple</td>
+ * <td>array</td>
+ * <td>path, header</td>
+ * <td>Simple style parameters defined by RFC6570. This option replaces
+ * collectionFormat with a csv value from OpenAPI 2.0.</td>
+ * </tr>
+ * <tr>
+ * <td>spaceDelimited</td>
+ * <td>array</td>
+ * <td>query</td>
+ * <td>Space separated array values. This option replaces collectionFormat equal
+ * to ssv from OpenAPI 2.0.</td>
+ * </tr>
+ * <tr>
+ * <td>pipeDelimited</td>
+ * <td>array</td>
+ * <td>query</td>
+ * <td>Pipe separated array values. This option replaces collectionFormat equal
+ * to pipes from OpenAPI 2.0.</td>
+ * </tr>
+ * <tr>
+ * <td>deepObject</td>
+ * <td>object</td>
+ * <td>query</td>
+ * <td>Provides a simple way of rendering nested objects using form
+ * parameters.</td>
+ * </tr>
+ * </table>
+ * 
+ * @see <a href=
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameterObject">OpenAPI
+ *      Specification Parameter Object</a>
  */
 public interface Parameter extends Extensible {
 
 	/**
-	 * Gets or Sets style
+	 * The values allowed for the style field.
 	 */
 	enum StyleEnum {
 	    MATRIX("matrix"),
@@ -56,387 +280,328 @@ public String toString() {
 	}
 
 	/**
-	 * returns the name property from a Parameter instance.
+	 * Returns the name property from a Parameter instance.
 	 *
-	 * @return String name
+	 * @return the name of the parameter
 	 **/
-
 	String getName();
 
 	/**
-	 * Sets the name property of a Parameter instance
-	 * to the parameter.
+	 * Sets the name property of a Parameter instance to the given string.
 	 *
-	 * @param name
+	 * @param name  the name of the parameter
 	 */
-
 	void setName(String name);
 
 	/**
-	 * Sets the name property of a Parameter instance
-	 * to the parameter and returns the instance.
+	 * Sets the name property of a Parameter instance to the given string.
 	 *
-	 * @param name
-	 * @return Parameter instance with the modified name property
+	 * @param name  the name of the parameter
+	 * @return the current Parameter instance
 	 */
-
 	Parameter name(String name);
 
 	/**
-	 * returns the in property from a Parameter instance.
+	 * Returns the in property from a Parameter instance.
 	 *
-	 * @return String in
+	 * @return the location of the parameter
 	 **/
-
 	String getIn();
 
 	/**
-	 * Sets the in property of a Parameter instance
-	 * to the parameter.
-	 * If in property is set to path then also sets
-	 * required property to true.
+	 * Sets the in property of a Parameter instance to the given string. If the
+	 * in property is set to "path" then also sets the required property to
+	 * true.
 	 *
-	 * @param in
+	 * @param in  the location of the parameter
 	 */
-
 	void setIn(String in);
 
 	/**
-	 * Sets the in property of a Parameter instance
-	 * to the parameter and returns the instance.
+	 * Sets the in property of a Parameter instance to the given string. If the
+	 * in property is set to "path" then also sets the required property to
+	 * true.
 	 *
-	 * @param in
-	 * @return Parameter instance with the modified in property
+	 * @param in  the location of the parameter
+	 * @return the current Parameter instance
 	 */
-
 	Parameter in(String in);
 
 	/**
-	 * returns the description property from a Parameter instance.
+	 * Returns the description property from a Parameter instance.
 	 *
-	 * @return String description
+	 * @return a brief description of the parameter
 	 **/
-
 	String getDescription();
 
 	/**
 	 * Sets the description property of a Parameter instance
-	 * to the parameter.
+	 * to the given string.
 	 *
-	 * @param description
+	 * @param description  a brief description of the parameter
 	 */
-
 	void setDescription(String description);
 
 	/**
 	 * Sets the description property of a Parameter instance
-	 * to the parameter and returns the instance.
+	 * to the given string.
 	 *
-	 * @param description
-	 * @return Parameter instance with the modified description property
+	 * @param description  a brief description of the parameter
+	 * @return the current Parameter instance
 	 */
-
 	Parameter description(String description);
 
 	/**
-	 * returns the required property from a Parameter instance.
+	 * Returns the required property from a Parameter instance.
 	 *
-	 * @return Boolean required
+	 * @return indicates whether this parameter is mandatory
 	 **/
-
 	Boolean getRequired();
 
 	/**
-	 * Sets the required property of a Parameter instance
-	 * to the parameter.
+	 * Sets the required property of a Parameter instance to the given value.
 	 *
-	 * @param required
+	 * @param required  indicates whether this parameter is mandatory
 	 */
-
 	void setRequired(Boolean required);
 
 	/**
-	 * Sets the required property of a Parameter instance
-	 * to the parameter and returns the instance.
+	 * Sets the required property of a Parameter instance to the given value.
 	 *
-	 * @param required
-	 * @return Parameter instance with the modified required property
+	 * @param required  indicates whether this parameter is mandatory
+	 * @return the current Parameter instance
 	 */
-
 	Parameter required(Boolean required);
 
 	/**
-	 * returns the deprecated property from a Parameter instance.
+	 * Returns the deprecated property from a Parameter instance.
 	 *
-	 * @return Boolean deprecated
+	 * @return specifies that a parameter is deprecated
 	 **/
-
 	Boolean getDeprecated();
 
 	/**
-	 * Sets the deprecated property of a Parameter instance
-	 * to the parameter.
+	 * Sets the deprecated property of a Parameter instance to the given value.
 	 *
-	 * @param deprecated
+	 * @param deprecated  specifies that a parameter is deprecated
 	 */
-
 	void setDeprecated(Boolean deprecated);
 
 	/**
-	 * Sets the deprecated property of a Parameter instance
-	 * to the parameter and returns the instance.
+	 * Sets the deprecated property of a Parameter instance to the given value.
 	 *
-	 * @param deprecated
-	 * @return Parameter instance with the modified deprecated property
+	 * @param deprecated  specifies that a parameter is deprecated
+	 * @return the current Parameter instance
 	 */
-
 	Parameter deprecated(Boolean deprecated);
 
 	/**
-	 * returns the allowEmptyValue property from a Parameter instance.
+	 * Returns the allowEmptyValue property from a Parameter instance.
 	 *
-	 * @return Boolean allowEmptyValue
+	 * @return specifies the ability to pass empty-valued parameters
 	 **/
-
 	Boolean getAllowEmptyValue();
 
 	/**
-	 * Sets the allowEmptyValue property of a Parameter instance
-	 * to the parameter.
+	 * Sets the allowEmptyValue property of a Parameter instance to the given value.
 	 *
-	 * @param allowEmptyValue
+	 * @param allowEmptyValue  specifies the ability to pass empty-valued parameters
 	 */
-
 	void setAllowEmptyValue(Boolean allowEmptyValue);
 
 	/**
-	 * Sets the allowEmptyValue property of a Parameter instance
-	 * to the parameter and returns the instance.
+	 * Sets the allowEmptyValue property of a Parameter instance to the given value.
 	 *
-	 * @param allowEmptyValue
-	 * @return Parameter instance with the modified allowEmptyValue property
+	 * @param allowEmptyValue  specifies the ability to pass empty-valued parameters
+	 * @return the current Parameter instance
 	 */
-
 	Parameter allowEmptyValue(Boolean allowEmptyValue);
 
 	/**
-	 * returns the style property from a Parameter instance.
+	 * Returns the style property from a Parameter instance.
 	 *
-	 * @return StyleEnum style
+	 * @return describes how the parameter value will be serialized
 	 **/
-
 	Parameter.StyleEnum getStyle();
 
 	/**
-	 * Sets the style property of a Parameter instance
-	 * to the parameter.
+	 * Sets the style property of a Parameter instance to the given value.
 	 *
-	 * @param style
+	 * @param style  describes how the parameter value will be serialized
 	 */
-
 	void setStyle(Parameter.StyleEnum style);
 
 	/**
-	 * Sets the style property of a Parameter instance
-	 * to the parameter and returns the instance.
+	 * Sets the style property of a Parameter instance to the given value.
 	 *
-	 * @param style
-	 * @return Parameter instance with the modified style property
+	 * @param style  describes how the parameter value will be serialized
+	 * @return the current Parameter instance
 	 */
-
 	Parameter style(Parameter.StyleEnum style);
 
 	/**
-	 * returns the explode property from a Parameter instance.
+	 * Returns the explode property from a Parameter instance.
 	 *
-	 * @return Boolean explode
+	 * @return whether parameter values of type "array" or "object" generate separate parameters for each value
 	 **/
-
 	Boolean getExplode();
 
 	/**
-	 * Sets the explode property of a Parameter instance
-	 * to the parameter.
+	 * Sets the explode property of a Parameter instance to the given value.
 	 *
-	 * @param explode
+	 * @param explode  whether parameter values of type "array" or "object" generate separate parameters for each value
 	 */
-
 	void setExplode(Boolean explode);
 
 	/**
-	 * Sets the explode property of a Parameter instance
-	 * to the parameter and returns the instance.
+	 * Sets the explode property of a Parameter instance to the given value.
 	 *
-	 * @param explode
-	 * @return Parameter instance with the modified explode property
+	 * @param explode  whether parameter values of type "array" or "object" generate separate parameters for each value
+	 * @return the current Parameter instance
 	 */
-
 	Parameter explode(Boolean explode);
 
 	/**
-	 * returns the allowReserved property from a Parameter instance.
+	 * Returns the allowReserved property from a Parameter instance.
 	 *
-	 * @return Boolean allowReserved
+	 * @return specifies whether the parameter value should allow reserved characters
 	 **/
-
 	Boolean getAllowReserved();
 
 	/**
-	 * Sets the allowReserved property of a Parameter instance
-	 * to the parameter.
+	 * Sets the allowReserved property of a Parameter instance to the given value.
 	 *
-	 * @param allowReserved
+	 * @param allowReserved  specifies whether the parameter value should allow reserved characters
 	 */
-
 	void setAllowReserved(Boolean allowReserved);
 
 	/**
-	 * Sets the allowReserved property of a Parameter instance
-	 * to the parameter and returns the instance.
+	 * Sets the allowReserved property of a Parameter instance to the given value.
 	 *
-	 * @param allowReserved
-	 * @return Parameter instance with the modified allowReserved property
+	 * @param allowReserved  specifies whether the parameter value should allow reserved characters
+	 * @return the current Parameter instance
 	 */
-
 	Parameter allowReserved(Boolean allowReserved);
 
 	/**
-	 * returns the schema property from a Parameter instance.
+	 * Returns the schema property from a Parameter instance.
 	 *
-	 * @return Schema schema
+	 * @return schema defining the type used for the parameter
 	 **/
-
 	Schema getSchema();
 
 	/**
-	 * Sets the schema property of a Parameter instance
-	 * to the parameter.
+	 * Sets the schema property of a Parameter instance to the given value.
 	 *
-	 * @param schema
+	 * @param schema  schema defining the type used for the parameter
 	 */
-
 	void setSchema(Schema schema);
 
 	/**
-	 * Sets the schema property of a Parameter instance
-	 * to the parameter and returns the instance.
+	 * Sets the schema property of a Parameter instance to the given value.
 	 *
-	 * @param schema
-	 * @return Parameter instance with the modified schema property
+	 * @param schema  schema defining the type used for the parameter
+	 * @return the current Parameter instance
 	 */
-
 	Parameter schema(Schema schema);
 
 	/**
-	 * returns the examples property from a Parameter instance.
+	 * Returns the examples property from a Parameter instance.
 	 *
-	 * @return Map&lt;String, Example&gt; examples
+	 * @return examples of the media type
 	 **/
-
 	Map<String, Example> getExamples();
 
+	/**
+	 * Sets the examples property of a Parameter instance to the given value.
+	 *
+	 * @param examples  examples of the media type
+	 */
 	void setExamples(Map<String, Example> examples);
 
 	/**
-	 * Sets the examples property of a Parameter instance
-	 * to the parameter.
+	 * Sets the examples property of a Parameter instance to the given value.
 	 *
-	 * @param examples
+	 * @param examples  examples of the media type
+	 * @return the current Parameter instance
 	 */
-
 	Parameter examples(Map<String, Example> examples);
 
 	/**
-	 * Adds an example item to the examples property of a Parameter instance
-	 * at the specified key and returns the instance.
-	 * If examples is null, creates a new HashMap and adds item
+	 * Adds an example of the media type using the specified key.
 	 *
-	 * @param key
-	 * @param examplesItem
-	 * @return Parameter instance with the added example item
+	 * @param key string to represent the example
+	 * @param examplesItem  example of the media type
+	 * @return the current Parameter instance
 	 */
-
 	Parameter addExamples(String key, Example examplesItem);
 
 	/**
-	 * returns the example property from a Parameter instance.
+	 * Returns the example property from a Parameter instance.
 	 *
-	 * @return String example
+	 * @return example of the media type
 	 **/
-
-	String getExample();
+	Object getExample();
 
 	/**
-	 * Sets the example property of a Parameter instance
-	 * to the parameter.
+	 * Sets the example property of a Parameter instance to the given object.
 	 *
-	 * @param example
+	 * @param example  example of the media type
 	 */
-
-	void setExample(String example);
+	void setExample(Object example);
 
 	/**
-	 * Sets the example property of a Parameter instance
-	 * to the parameter and returns the instance.
+	 * Sets the example property of a Parameter instance to the given object.
 	 *
-	 * @param example
-	 * @return Parameter instance with the modified example property
+	 * @param example  example of the media type
+	 * @return the current Parameter instance
 	 */
-
-	Parameter example(String example);
+	Parameter example(Object example);
 
 	/**
-	 * returns the content property from a Parameter instance.
+	 * Returns the content property from a Parameter instance.
 	 *
-	 * @return Content content
+	 * @return a map containing the media representations for the parameter
 	 **/
-
 	Content getContent();
 
 	/**
-	 * Sets the content property of a Parameter instance
-	 * to the parameter.
+	 * Sets the content property of a Parameter instance to the given object.
 	 *
-	 * @param content
+	 * @param content  a map containing the media representations for the parameter
 	 */
-
 	void setContent(Content content);
 
 	/**
-	 * Sets the content property of a Parameter instance
-	 * to the parameter and returns the instance.
+	 * Sets the content property of a Parameter instance to the given object.
 	 *
-	 * @param content
-	 * @return Parameter instance with the modified content property
+	 * @param content  a map containing the media representations for the parameter
+	 * @return the current Parameter instance
 	 */
-
 	Parameter content(Content content);
 
 	/**
-	 * returns the $ref property from a Parameter instance.
+	 * Returns the reference property from a Parameter instance.
 	 *
-	 * @return String $ref
+	 * @return  a reference to a parameter object in an OpenAPI document
 	 **/
-
-	String get$ref();
+	String getReference();
 
 	/**
-	 * Sets $ref property of a Parameter instance
-	 * to the parameter.
+	 * Sets reference property of a Parameter instance to the given string.
 	 *
-	 * @param $ref
+	 * @param reference  a reference to a header object in an OpenAPI document
+	 *            especially in the components in this OpenAPI document
 	 */
-
-	void set$ref(String $ref);
+	void setReference(String reference);
 
 	/**
-	 * Sets $ref property of a Parameter instance
-	 * to the parameter and return the instance.
+	 * Sets reference property of a Parameter instance to the given string.
 	 *
-	 * @param $ref
-	 * @return Parameter instance with the set $ref property.
+	 * @param reference  a reference to a header object in an OpenAPI document
+	 *            especially in the components in this OpenAPI document
+	 * @return the current Parameter instance
 	 */
-
-	Parameter $ref(String $ref);
+	Parameter reference(String reference);
 
 }
\ No newline at end of file

From be868bd9755b683634835f197f584f33b109ed79 Mon Sep 17 00:00:00 2001
From: Paul Gooderham <turkeyonmarblerye@gmail.com>
Date: Thu, 26 Oct 2017 11:45:34 -0400
Subject: [PATCH 17/23] Update operations in PathItem to match latest proposal.
 8732

Signed-off-by: Paul Gooderham <turkeyonmarblerye@gmail.com>
---
 .../microprofile/openapi/models/PathItem.java | 48 +++++++++----------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
index 47a751f1e..058e69801 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
@@ -186,14 +186,14 @@ enum HttpMethod {
 	 *
 	 * @return definition of a GET operation on this path
 	 **/
-	Operation getGetOperation();
+	Operation getGET();
 
 	/**
 	 * Sets this PathItem's get property to the given operation.
 	 *
 	 * @param get  definition of a GET operation
 	 **/
-	void setGetOperation(Operation get);
+	void setGET(Operation get);
 
 	/**
 	 * Sets this PathItem's get property to the given operation.
@@ -201,21 +201,21 @@ enum HttpMethod {
 	 * @param get  definition of a GET operation
 	 * @return the current PathItem instance
 	 **/
-	PathItem get(Operation get);
+	PathItem GET(Operation get);
 
 	/**
 	 * Returns the put property from a PathItem instance.
 	 *
 	 * @return definition of a PUT operation on this path
 	 **/
-	Operation getPutOperation();
+	Operation getPUT();
 
 	/**
 	 * Sets this PathItem's put property to the given operation.
 	 *
 	 * @param put  definition of a PUT operation
 	 **/
-	void setPutOperation(Operation put);
+	void setPUT(Operation put);
 
 	/**
 	 * Sets this PathItem's put property to the given operation.
@@ -223,21 +223,21 @@ enum HttpMethod {
 	 * @param put  definition of a PUT operation
 	 * @return the current PathItem instance
 	 **/
-	PathItem put(Operation put);
+	PathItem PUT(Operation put);
 
 	/**
 	 * Returns the post property from a PathItem instance.
 	 *
 	 * @return definition of a POST operation on this path
 	 **/
-	Operation getPostOperation();
+	Operation getPOST();
 
 	/**
 	 * Sets this PathItem's post property to the given operation.
 	 *
 	 * @param post  definition of a PUT operation
 	 **/
-	void setPostOperation(Operation post);
+	void setPOST(Operation post);
 
 	/**
 	 * Sets this PathItem's post property to the given operation.
@@ -245,21 +245,21 @@ enum HttpMethod {
 	 * @param post  definition of a PUT operation
 	 * @return the current PathItem instance
 	 **/
-	PathItem post(Operation post);
+	PathItem POST(Operation post);
 
 	/**
 	 * Returns the delete property from a PathItem instance.
 	 *
 	 * @return definition of a DELETE operation on this path
 	 **/
-	Operation getDeleteOperation();
+	Operation getDELETE();
 
 	/**
 	 * Sets this PathItem's delete property to the given operation.
 	 *
 	 * @param delete  definition of a DELETE operation
 	 **/
-	void setDeleteOperation(Operation delete);
+	void setDELETE(Operation delete);
 
 	/**
 	 * Sets this PathItem's delete property to the given operation.
@@ -267,21 +267,21 @@ enum HttpMethod {
 	 * @param delete  definition of a DELETE operation
 	 * @return the current PathItem instance
 	 **/
-	PathItem delete(Operation delete);
+	PathItem DELETE(Operation delete);
 
 	/**
 	 * Returns the options property from a PathItem instance.
 	 *
 	 * @return definition of an OPTIONS operation on this path
 	 **/
-	Operation getOptionsOperation();
+	Operation getOPTIONS();
 
 	/**
 	 * Sets this PathItem's options property to the given operation.
 	 *
 	 * @param options  definition of an OPTIONS operation
 	 **/
-	void setOptionsOperation(Operation options);
+	void setOPTIONS(Operation options);
 
 	/**
 	 * Sets this PathItem's options property to the given operation.
@@ -289,21 +289,21 @@ enum HttpMethod {
 	 * @param options  definition of an OPTIONS operation
 	 * @return the current PathItem instance
 	 **/
-	PathItem options(Operation options);
+	PathItem OPTIONS(Operation options);
 
 	/**
 	 * Returns the head property from a PathItem instance.
 	 *
 	 * @return definition of a HEAD operation on this path
 	 **/
-	Operation getHeadOperation();
+	Operation getHEAD();
 
 	/**
 	 * Sets this PathItem's head property to the given operation.
 	 *
 	 * @param head  definition of a HEAD operation
 	 **/
-	void setHeadOperation(Operation head);
+	void setHEAD(Operation head);
 
 	/**
 	 * Sets this PathItem's head property to the given operation.
@@ -311,21 +311,21 @@ enum HttpMethod {
 	 * @param head  definition of a HEAD operation
 	 * @return the current PathItem instance
 	 **/
-	PathItem head(Operation head);
+	PathItem HEAD(Operation head);
 
 	/**
 	 * Returns the patch property from a PathItem instance.
 	 *
 	 * @return definition of a PATCH operation on this path
 	 **/
-	Operation getPatchOperation();
+	Operation getPATCH();
 
 	/**
 	 * Sets this PathItem's patch property to the given operation.
 	 *
 	 * @param patch  definition of a PATCH operation
 	 **/
-	void setPatchOperation(Operation patch);
+	void setPATCH(Operation patch);
 
 	/**
 	 * Sets this PathItem's patch property to the given operation.
@@ -333,21 +333,21 @@ enum HttpMethod {
 	 * @param patch  definition of a PATCH operation
 	 * @return the current PathItem instance
 	 **/
-	PathItem patch(Operation patch);
+	PathItem PATCH(Operation patch);
 
 	/**
 	 * Returns the trace property from a PathItem instance.
 	 *
 	 * @return definition of a TRACE operation on this path
 	 **/
-	Operation getTraceOperation();
+	Operation getTRACE();
 
 	/**
 	 * Sets this PathItem's trace property to the given operation.
 	 *
 	 * @param trace  definition of a TRACE operation
 	 **/
-	void setTraceOperation(Operation trace);
+	void setTRACE(Operation trace);
 
 	/**
 	 * Sets this PathItem's trace property to the given operation.
@@ -355,7 +355,7 @@ enum HttpMethod {
 	 * @param trace  definition of a TRACE operation
 	 * @return the current PathItem instance
 	 **/
-	PathItem trace(Operation trace);
+	PathItem TRACE(Operation trace);
 
 	/**
 	 * Returns a list of all the operations for this path item.

From 4b135ea4d187eb8e1cd89527fca0b6389172b893 Mon Sep 17 00:00:00 2001
From: Paul Gooderham <turkeyonmarblerye@gmail.com>
Date: Thu, 26 Oct 2017 14:57:20 -0400
Subject: [PATCH 18/23] Update the Javadocs for Discriminator, MediaType,
 CookieParameter, HeaderParameter, PathParameter and QueryParameter. Modify
 the model of Mediatype to conform to the spec. 8732

Signed-off-by: Paul Gooderham <turkeyonmarblerye@gmail.com>
---
 .../openapi/models/media/Discriminator.java   |  72 +++++---
 .../openapi/models/media/MediaType.java       | 158 ++++++++++--------
 .../models/parameters/CookieParameter.java    |   2 +
 .../models/parameters/HeaderParameter.java    |   2 +
 .../models/parameters/PathParameter.java      |   2 +
 .../models/parameters/QueryParameter.java     |   2 +
 6 files changed, 147 insertions(+), 91 deletions(-)

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 2fd2e4210..18a1c120f 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
@@ -21,60 +21,92 @@
 
 import org.eclipse.microprofile.openapi.models.Constructible;
 
+/**
+ * Discriminator
+ * <p>
+ * When request bodies or response payloads may be one of a number of different
+ * schemas, a discriminator object can be used to aid in serialization,
+ * deserialization, and validation. The discriminator is a specific object in a
+ * schema which is used to inform the consumer of the specification of an
+ * alternative schema based on the value associated with it.
+ * <p>
+ * When using the discriminator, inline schemas will not be considered.
+ * <p>
+ * Fixed Fields
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
+ * <tr>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td>propertyName</td>
+ * <td>string</td>
+ * <td>REQUIRED. The name of the property in the payload that will hold the
+ * discriminator value.</td>
+ * </tr>
+ * <tr>
+ * <td>mapping</td>
+ * <td>Map[string, string]</td>
+ * <td>An object to hold mappings between payload values and schema names or
+ * references.</td>
+ * </tr>
+ * </table>
+ * 
+ * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminator-object">OpenAPI Specification Discriminator Object</a>
+ */
 public interface Discriminator extends Constructible {
 
 	/**
-	 * sets this Discriminator's propertyName property to the given propertyName and
-	 * returns this instance of Discriminator
+	 * Sets this Discriminator's propertyName property to the given string.
 	 *
-	 * @param String propertyName
-	 * @return Discriminator
+	 * @param propertyName the name of the property in the payload that will hold the discriminator value
+	 * @return the current Discriminator instance
 	 */
 	Discriminator propertyName(String propertyName);
 
 	/**
-	 * returns the propertyName property from a Discriminator instance.
+	 * Returns the propertyName property from a Discriminator instance.
 	 *
-	 * @return String propertyName
+	 * @return the name of the property in the payload that will hold the discriminator value
 	 **/
 	String getPropertyName();
 
 	/**
-	 * sets this Discriminator's propertyName property to the given propertyName.
+	 * Sets this Discriminator's propertyName property to the given propertyName.
 	 *
-	 * @param String propertyName
+	 * @param propertyName  the name of the property in the payload that will hold the discriminator value
 	 */
 	void setPropertyName(String propertyName);
 
 	/**
-	 * maps the given name to the given value and store it in this Discriminator's mapping property.
+	 * Maps the given name to the given value and stores it in this Discriminator's mapping property.
 	 * 
-	 * @param String name
-	 * @param String value
-	 * @return Discriminator
+	 * @param name  a key which will be compared to information from a request body or response payload.
+	 * @param value  a schema name or reference
+	 * @return the current Discriminator instance
 	 */
 	Discriminator mapping(String name, String value);
 
 	/**
-	 * sets this Discriminator's mapping property to the given mapping and
-	 * returns this instance of Discriminator
+	 * Sets this Discriminator's mapping property to the given map object. 
 	 *
-	 * @param Map&lt;String, String&gt; mapping
-	 * @return Discriminator
+	 * @param mapping  a map containing keys and schema names or references
+	 * @return the current Discriminator instance
 	 */
 	Discriminator mapping(Map<String, String> mapping);
 
 	/**
-	 * returns the mapping property from a Discriminator instance.
+	 * Returns the mapping property from a Discriminator instance.
 	 *
-	 * @return Map&lt;String, String&gt; mapping
+	 * @return a map containing keys and schema names or references
 	 **/
 	Map<String, String> getMapping();
 
 	/**
-	 * sets this Discriminator's mapping property to the given mapping.
+	 * Sets this Discriminator's mapping property to the given map object.
 	 *
-	 * @param Map&lt;String, String&gt; mapping
+	 * @param mapping  a map containing keys and schema names or references
 	 */
 	void setMapping(Map<String, String> mapping);
 
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 e17f7081e..654d6b887 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
@@ -25,145 +25,161 @@
 
 /**
  * MediaType
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#mediaTypeObject"
+ * <p>
+ * Each Media Type Object provides a schema and examples for the media type
+ * identified by its key.
+ * <p>
+ * Fixed Fields
+ * <table border=1 cellpadding="8" style="border-collapse: collapse">
+ * <tr>
+ * <th>Field Name</th>
+ * <th>Type</th>
+ * <th>Description</th>
+ * </tr>
+ * <tr>
+ * <td>schema</td>
+ * <td>{@link Schema Schema Object} | {@link Schema Reference Object}</td>
+ * <td>The schema defining the type used for the request body.</td>
+ * </tr>
+ * <tr>
+ * <td>example</td>
+ * <td>Any</td>
+ * <td>Example of the media type. The example object SHOULD be in the correct
+ * format as specified by the media type. The example object is mutually
+ * exclusive of the examples object. Furthermore, if referencing a schema which
+ * contains an example, the example value SHALL override the example provided by
+ * the schema.</td>
+ * </tr>
+ * <tr>
+ * <td>examples</td>
+ * <td>Map[ string, {@link Example Example Object} | {@link Example Reference Object}]</td>
+ * <td>Examples of the media type. Each example object SHOULD match the media
+ * type and specified schema if present. The examples object is mutually
+ * exclusive of the example object. Furthermore, if referencing a schema which
+ * contains an example, the examples value SHALL override the example provided
+ * by the schema.</td>
+ * </tr>
+ * <tr>
+ * <td>encoding</td>
+ * <td>Map[string, {@link Encoding Encoding Object}]</td>
+ * <td>A map between a property name and its encoding information. The key,
+ * being the property name, MUST exist in the schema as a property. The encoding
+ * object SHALL only apply to requestBody objects when the media type is
+ * multipart or application/x-www-form-urlencoded.</td>
+ * </tr>
+ * </table>
+ * 
+ * @see <a
+ *      href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#mediaTypeObject">OpenAPI
+ *      Specification Media Type Object</a>
  */
 public interface MediaType extends Constructible, Extensible {
 
 	/**
-	 * returns the schema property from a MediaType instance.
+	 * Returns the schema property from a MediaType instance.
 	 *
-	 * @return Schema schema
+	 * @return the schema defining the type used for the request body
 	 **/
-
 	Schema getSchema();
 
 	/**
-	 * Sets schema field of a MediaType instance to the
-	 * parameter.
+	 * Sets the schema field of a MediaType instance to the
+	 * given schema object.
 	 *
-	 * @param schema
+	 * @param schema  the schema defining the type used for the request body
 	 */
-
 	void setSchema(Schema schema);
 
 	/**
-	 * Sets schema property of a MediaType instance to the
-	 * parameter and returns the instance.
+	 * Sets the schema field of a MediaType instance to the given schema object.
 	 *
-	 * @param schema
-	 * @return MediaType instance with the set schema property
+	 * @param schema  the schema defining the type used for the request body
+	 * @return the current MediaType instance
 	 */
-
 	MediaType schema(Schema schema);
 
 	/**
-	 * returns the examples map of String to Example from a MediaType instance.
+	 * Returns the collection of examples from a MediaType instance.
 	 *
-	 * @return Map&lt;String, Example&gt; examples
+	 * @return examples of the media type
 	 **/
-
 	Map<String, Example> getExamples();
 
 	/**
-	 * Sets examples field of a MediaType instance to the
-	 * parameter.
+	 * Sets the examples field of a MediaType instance to the given map object.
 	 *
-	 * @param examples
+	 * @param examples  examples of the media type
 	 */
-
 	void setExamples(Map<String, Example> examples);
 
 	/**
-	 * Sets examples field of a MediaType instance to the
-	 * parameter and returns the instance.
+	 * Sets the examples field of a MediaType instance to the given map object.
 	 *
-	 * @param examples
-	 * @return MediaType instance with the set examples property
+	 * @param examples  examples of the media type
+	 * @return the current MediaType instance
 	 */
-
 	MediaType examples(Map<String, Example> examples);
 
 	/**
-	 * Adds an example item to examples map of a MediaType instance
-	 * and returns the instance.
-	 * <p>
-	 * If the examples property is null, creates a new HashMap
-	 * and adds the item to it.
+	 * Adds an example item to the examples map of a MediaType instance.
 	 *
-	 * @param key
-	 * @param examplesItem
-	 * @return MediaType instance with the set example item
+	 * @param key  any unique name to identify the example object
+	 * @param examplesItem  an example of a media type
+	 * @return the current MediaType instance
 	 */
-
 	MediaType addExamples(String key, Example examplesItem);
 
 	/**
-	 * returns the example property from a MediaType instance.
+	 * Returns the example property from a MediaType instance.
 	 *
-	 * @return String example
+	 * @return an example of the media type
 	 **/
-
-	String getExample();
+	Object getExample();
 
 	/**
-	 * Sets example property of a MediaType instance to the
-	 * parameter.
+	 * Sets the example property of a MediaType instance to the given value.
 	 *
-	 * @param example
+	 * @param example  an example of the media type
 	 */
-
-	void setExample(String example);
+	void setExample(Object example);
 
 	/**
-	 * Sets example property of a MediaType instance to the
-	 * parameter and returns the instance.
+	 * Sets the example property of a MediaType instance to the given value.
 	 *
-	 * @param example
-	 * @return MediaType instance with the set example property
+	 * @param example  an example of the media type
+	 * @return the current MediaType instance
 	 */
-
-	MediaType example(String example);
+	MediaType example(Object example);
 
 	/**
-	 * returns the encoding property from a MediaType instance.
+	 * Returns the encoding property from a MediaType instance.
 	 *
-	 * @return Encoding encoding
+	 * @return a map between a property name and its encoding information
 	 **/
-
 	Map<String, Encoding> getEncoding();
 
 	/**
-	 * Sets encoding property of a MediaType instance to the
-	 * parameter.
+	 * Sets encoding property of a MediaType instance to the given map object.
 	 *
-	 * @param encoding
+	 * @param encoding  a map between property names and their encoding information
 	 */
-
 	void setEncoding(Map<String, Encoding> encoding);
 
 	/**
-	 * Sets encoding property of a MediaType instance to the
-	 * parameter and returns the instance.
+	 * Sets encoding property of a MediaType instance to the given map object.
 	 *
-	 * @param encoding
-	 * @return MediaType instance with the set encoding property
+	 * @param encoding  a map between property names and their encoding information
+	 * @return the current MediaType instance
 	 */
-
 	MediaType encoding(Map<String, Encoding> encoding);
 
 	/**
-	 * Adds an Encoding item to encoding map of a MediaType instance
-	 * and returns the instance.
-	 * <p>
-	 * If the encoding property is null, creates a new HashMap
-	 * and adds the item to it.
+	 * Adds an Encoding item to the encoding property of a MediaType instance.
 	 *
-	 * @param String key
-	 * @param Encoding encodingItem
-	 * @return MediaType instance with the added encoding item
+	 * @param key a property name in the schema
+	 * @param encodingItem  an encoding definition to apply to the schema property.
+	 * @return the current MediaType instance
 	 */
-
 	MediaType addEncoding(String key, Encoding encodingItem);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/CookieParameter.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/CookieParameter.java
index 60c050cc2..cf0ad01f2 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/CookieParameter.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/CookieParameter.java
@@ -21,6 +21,8 @@
 
 /**
  * CookieParameter
+ * <p>
+ * A cookie parameter is a {@link Parameter Parameter} where the "in" property has the value "cookie."
  */
 public interface CookieParameter extends Constructible, Parameter {
 
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/HeaderParameter.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/HeaderParameter.java
index 4fe2d4860..91654a596 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/HeaderParameter.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/HeaderParameter.java
@@ -21,6 +21,8 @@
 
 /**
  * HeaderParameter
+ * <p>
+ * A header parameter is a {@link Parameter Parameter} where the "in" property has the value "header."
  */
 public interface HeaderParameter extends Constructible, Parameter {
 
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/PathParameter.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/PathParameter.java
index 51a5d7a30..3154d2e1a 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/PathParameter.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/PathParameter.java
@@ -21,6 +21,8 @@
 
 /**
  * PathParameter
+ * <p>
+ * A path parameter is a {@link Parameter Parameter} where the "in" property has the value "path."
  */
 public interface PathParameter extends Constructible, Parameter {
 
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/QueryParameter.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/QueryParameter.java
index 37da1a1f2..fee8bddda 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/QueryParameter.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/QueryParameter.java
@@ -21,6 +21,8 @@
 
 /**
  * QueryParameter
+ * <p>
+ * A query parameter is a {@link Parameter Parameter} where the "in" property has the value "query."
  */
 public interface QueryParameter extends Constructible, Parameter {
 

From c23100251ff64f1f40b9173bdde6185fc989dc14 Mon Sep 17 00:00:00 2001
From: Anna Safonov <anna.safonov@ibm.com>
Date: Fri, 27 Oct 2017 11:14:07 -0400
Subject: [PATCH 19/23] Updated XML model

Signed-off-by: Anna Safonov <anna.safonov@ibm.com>
---
 .../openapi/models/media/XML.java             | 157 +++++++++++-------
 1 file changed, 99 insertions(+), 58 deletions(-)

diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java
index c48527947..2bd14f4f3 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java
@@ -21,145 +21,186 @@
 import org.eclipse.microprofile.openapi.models.Extensible;
 
 /**
- * XML
- *
+ * A metadata object that allows for more fine-tuned XML model definitions.
+ * When using arrays, XML element names are not inferred (for singular/plural forms) and 
+ * the name property SHOULD be used to add that information.
+ * <p>
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#xmlObject"
  */
 public interface XML extends Constructible, Extensible {
 
-	/**
-	 * returns the name property from a XML instance.
-	 *
+	/** 
+	 * This method returns the name property from XML instance.
+	 * <p>
+	 * The name property replaces the name of the element/attribute 
+	 * used for the described schema property.
+	 * <p>
 	 * @return String name
+	 * @see https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#xml-object
 	 **/
-
 	String getName();
 
 	/**
-	 * Sets the name property of an XML instance
-	 * to the parameter.
-	 *
+	 * This method sets the name property of XML instance
+	 * to the given String argument.
+	 * <p>
+	 * The name property replaces the name of the element/attribute 
+	 * used for the described schema property.
+	 * <p>
 	 * @param name
+	 * @see https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#xml-object
 	 */
-
 	void setName(String name);
 
 	/**
-	 * Sets the name property of an XML instance
-	 * to the parameter and returns the instance.
-	 *
+	 * This method sets the name property of XML instance
+	 * to the given String argument and returns the modified instance.
+	 * <p>
+	 * The name property replaces the name of the element/attribute 
+	 * used for the described schema property.
+	 * <p>
 	 * @param name
 	 * @return XML instance with the set name property
+	 * @see https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#xml-object
 	 */
-
 	XML name(String name);
 
 	/**
-	 * returns the namespace property from a XML instance.
-	 *
+	 * This method returns the namespace property of XML instance.
+	 * <p>
+	 * The namespace property is the URI of the namespace definition.
+	 * Value MUST be in the form of an absolute URI.
+	 * <p>
 	 * @return String namespace
 	 **/
-
 	String getNamespace();
 
 	/**
-	 * Sets the namespace property of an XML instance
-	 * to the parameter.
-	 *
+	 * This method sets the namespace property of XML instance
+	 * to the given String argument.
+	 * <p>
+	 * The namespace property is the URI of the namespace definition.
+	 * Value MUST be in the form of an absolute URI.
+	 * <p>
 	 * @param namespace
 	 */
-
 	void setNamespace(String namespace);
 
 	/**
-	 * Sets the namespace property of an XML instance
-	 * to the parameter and returns the instance.
-	 *
+	 * This method sets the namespace property of XML instance
+	 * to the given String argument and returns the modified instance.
+	 * <p>
+	 * The namespace property is the URI of the namespace definition.
+	 * Value MUST be in the form of an absolute URI.
+	 * <p>
 	 * @param namespace
 	 * @return XML instance with the set namespace property
 	 */
-
 	XML namespace(String namespace);
 
 	/**
-	 * returns the prefix property from a XML instance.
-	 *
+	 * This method returns the prefix property of XML instance.
+	 * <p>
+	 * This property is a String prefix to be used for the name.
+	 * <p>
 	 * @return String prefix
 	 **/
-
 	String getPrefix();
 
 	/**
-	 * Sets the prefix property of an XML instance
-	 * to the parameter.
-	 *
+	 * This method sets the prefix property of XML instance
+	 * to the given String argument.
+	 * <p>
+	 * This property is a String prefix to be used for the name.
+	 * <p>
 	 * @param prefix
 	 */
-
 	void setPrefix(String prefix);
 
 	/**
-	 * Sets the prefix property of an XML instance
-	 * to the parameter and returns the instance.
-	 *
+	 * This method sets the prefix property of XML instance
+	 * to the given String argument and returns the modified instance.
+	 * <p>
+	 * This property is a String prefix to be used for the name.
+	 * <p>
 	 * @param prefix
 	 * @return XML instance with the set prefix property
 	 */
-
 	XML prefix(String prefix);
 
 	/**
-	 * returns the attribute property from a XML instance.
-	 *
+	 * This method returns the attribute property of XML instance.
+	 * <p>
+	 * Attribute property declares whether the property definition translates to an attribute 
+	 * instead of an element. 
+	 * Default value is FALSE.
+	 * <p>
 	 * @return Boolean attribute
 	 **/
-
 	Boolean getAttribute();
 
 	/**
-	 * Sets the attribute property of an XML instance
-	 * to the parameter.
-	 *
+	 * This method sets the attribute property of XML instance
+	 * to the given Boolean argument.
+	 * <p>
+	 * Attribute property declares whether the property definition translates to an attribute 
+	 * instead of an element. 
+	 * Default value is FALSE.
+	 * <p>
 	 * @param attribute
 	 */
-
 	void setAttribute(Boolean attribute);
 
 	/**
-	 * Sets the attribute property of an XML instance
-	 * to the parameter and returns the instance.
-	 *
+	 * This method sets the attribute property of XML instance
+	 * to the given Boolean argument and returns the modified instance.
+	 * <p>
+	 * Attribute property declares whether the property definition translates to an attribute 
+	 * instead of an element. 
+	 * Default value is FALSE.
+	 * <p>
 	 * @param attribute
 	 * @return XML instance with the set attribute property
 	 */
-
 	XML attribute(Boolean attribute);
 
 	/**
-	 * returns the wrapped property from a XML instance.
-	 *
+	 * This method returns the wrapped property of XML instance.
+	 * <p>
+	 * Wrapped property MAY be used only for an array definition. 
+	 * Signifies whether the array is wrapped. The definition takes effect only when defined
+	 * alongside type being array.
+	 * Default value is FALSE.
+	 * <p>
 	 * @return Boolean wrapped
 	 **/
-
 	Boolean getWrapped();
 
 	/**
-	 * Sets the wrapped property of an XML instance
-	 * to the parameter.
-	 *
+	 * This method sets the wrapped property of XML instance
+	 * to the given Boolean argument.
+	 * <p>
+	 * Wrapped property MAY be used only for an array definition. 
+	 * Signifies whether the array is wrapped. The definition takes effect only when defined
+	 * alongside type being array.
+	 * Default value is FALSE.
+	 * <p>
 	 * @param wrapped
 	 */
-
 	void setWrapped(Boolean wrapped);
 
 	/**
-	 * Sets the wrapped property of an XML instance
-	 * to the parameter and returns the instance.
-	 *
+	 * This method sets the wrapped property of XML instance
+	 * to the given Boolean argument and returns the modified instance.
+	 * <p>
+	 * Wrapped property MAY be used only for an array definition. 
+	 * Signifies whether the array is wrapped. The definition takes effect only when defined
+	 * alongside type being array.
+	 * Default value is FALSE.
+	 * <p>
 	 * @param wrapped
 	 * @return XML instance with the set wrapped property
 	 */
-
 	XML wrapped(Boolean wrapped);
 
 }
\ No newline at end of file

From bbe8baca6197a68ec7639ca8a7110bdc5dcc2a5f Mon Sep 17 00:00:00 2001
From: Michael Glavassevich <mrglavas@ca.ibm.com>
Date: Mon, 30 Oct 2017 15:46:37 -0400
Subject: [PATCH 20/23] Adding documentation to the Constructible interface.

Signed-off-by: Michael Glavassevich <mrglavas@ca.ibm.com>
---
 .../eclipse/microprofile/openapi/models/Constructible.java   | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/Constructible.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/Constructible.java
index 55015dbfa..d8c1be654 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/Constructible.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Constructible.java
@@ -16,6 +16,11 @@
 
 package org.eclipse.microprofile.openapi.models;
 
+/**
+ * Marker interface for OpenAPI model objects that can be constructed by the OASFactory.
+ * 
+ * @see org.eclipse.microprofile.openapi.OASFactory
+ */
 public interface Constructible {
 
 }

From ede33c29265ea332fa7ba4a14248f4ebcb234c82 Mon Sep 17 00:00:00 2001
From: Paul Gooderham <turkeyonmarblerye@gmail.com>
Date: Tue, 31 Oct 2017 10:44:39 -0400
Subject: [PATCH 21/23] Update the Javadocs to be more succinct. 8732

Signed-off-by: Paul Gooderham <turkeyonmarblerye@gmail.com>
---
 .../openapi/models/Components.java            |  99 ++------
 .../openapi/models/ExternalDocumentation.java |  19 --
 .../microprofile/openapi/models/OpenAPI.java  |  78 +-----
 .../openapi/models/Operation.java             | 101 +-------
 .../microprofile/openapi/models/PathItem.java |  91 +------
 .../microprofile/openapi/models/Paths.java    |  43 ++--
 .../openapi/models/examples/Example.java      |  47 +---
 .../openapi/models/headers/Header.java        | 179 +++-----------
 .../openapi/models/links/Link.java            | 109 +++------
 .../openapi/models/media/Discriminator.java   |  22 --
 .../openapi/models/media/MediaType.java       |  48 +---
 .../openapi/models/parameters/Parameter.java  | 228 ++----------------
 .../microprofile/openapi/models/tags/Tag.java |  24 --
 13 files changed, 152 insertions(+), 936 deletions(-)

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 5010a198c..48d0b8ba2 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
@@ -32,81 +32,23 @@
 /**
  * Components
  * <p>
- * Holds a set of reusable objects for different aspects of the OAS. All objects
- * defined within the components object will have no effect on the API unless
- * they are explicitly referenced from properties outside the components object.
+ * Holds a set of reusable objects for different aspects of the API
+ * specification. All objects defined within this object will have no effect on
+ * the API unless they are explicitly referenced from properties outside the
+ * components object.
  * <p>
- * Fixed Fields
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>schemas</td>
- * <td>Map[string, {@link Schema Schema Object } | {@link Schema Reference Object}]</td>
- * <td>An object to hold reusable Schema Objects.</td>
- * </tr>
- * <tr>
- * <td>responses</td>
- * <td>Map[string, {@link ApiResponse Response Object } | {@link ApiResponse Reference
- * Object}]</td>
- * <td>An object to hold reusable Response Objects.</td>
- * </tr>
- * <tr>
- * <td>parameters</td>
- * <td>Map[string, {@link Parameter Parameter Object } | {@link Parameter Reference
- * Object}]</td>
- * <td>An object to hold reusable Parameter Objects.</td>
- * </tr>
- * <tr>
- * <td>examples</td>
- * <td>Map[string, {@link Example Example Object } | {@link Example Reference
- * Object}]</td>
- * <td>An object to hold reusable Example Objects.</td>
- * </tr>
- * <tr>
- * <td>requestBodies</td>
- * <td>Map[string, {@link RequestBody Request Body Object } |
- * {@link RequestBody Reference Object}]</td>
- * <td>An object to hold reusable Request Body Objects.</td>
- * </tr>
- * <tr>
- * <td>headers</td>
- * <td>Map[string, {@link Header Header Object } | {@link Header Reference Object}]</td>
- * <td>An object to hold reusable Header Objects.</td>
- * </tr>
- * <tr>
- * <td>securitySchemes</td>
- * <td>Map[string, {@link SecurityScheme Security Scheme Object } |
- * {@link SecurityScheme Reference Object}]</td>
- * <td>An object to hold reusable Security Scheme Objects.</td>
- * </tr>
- * <tr>
- * <td>links</td>
- * <td>Map[string, {@link Link Link Object } | {@link Link Reference Object}]</td>
- * <td>An object to hold reusable Link Objects.</td>
- * </tr>
- * <tr>
- * <td>callbacks</td>
- * <td>Map[string, {@link Callback Callback Object } | {@link Callback Reference
- * Object}]</td>
- * <td>An object to hold reusable Callback Objects.</td>
- * </tr>
- * </table>
+ * All the fields are indexed by keys that must match the regular expression:
+ * <code>^[a-zA-Z0-9\.\-_]+$</code>.
  * <p>
- * All the fixed fields declared above are objects that MUST use keys that match
- * the regular expression: <code>^[a-zA-Z0-9\.\-_]+$</code>.
- * <p>
- * Field Name Examples:
+ * Key Examples:
  * <ul>
- * <li>User</li> 
- * <li>User_1</li> 
- * <li>User_Name</li> 
- * <li>user-name</li> 
+ * <li>User</li>
+ * <li>User_1</li>
+ * <li>User_Name</li>
+ * <li>user-name</li>
  * <li>my.org.User</li>
  * </ul>
+ * 
  * @see <a href=
  *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#componentsObject">
  *      OpenAPI Specification Components Object</a>
@@ -149,7 +91,8 @@ public interface Components extends Constructible, Extensible {
 	/**
 	 * Returns the responses property from a Components instance.
 	 *
-	 * @return a Map containing the keys and the reusable responses from API operations for this OpenAPI document
+	 * @return a Map containing the keys and the reusable responses from API
+	 *         operations for this OpenAPI document
 	 **/
 	Map<String, ApiResponse> getResponses();
 
@@ -182,9 +125,9 @@ public interface Components extends Constructible, Extensible {
 	/**
 	 * Returns the parameters property from a Components instance.
 	 *
-	 * @return a Map containing the keys and the reusable parameters of API operations for this OpenAPI document
+	 * @return a Map containing the keys and the reusable parameters of API
+	 *         operations for this OpenAPI document
 	 **/
-
 	Map<String, Parameter> getParameters();
 
 	/**
@@ -218,7 +161,6 @@ public interface Components extends Constructible, Extensible {
 	 *
 	 * @return a Map containing the keys and the reusable examples for this OpenAPI document
 	 **/
-
 	Map<String, Example> getExamples();
 
 	/**
@@ -272,10 +214,13 @@ public interface Components extends Constructible, Extensible {
 	Components requestBodies(Map<String, RequestBody> requestBodies);
 
 	/**
-	 * Adds the given request body to this Components' map of request bodies with the given string as its key.
+	 * 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 requestBodiesItem a reusable request body object
+	 * @param key
+	 *            a key conforming to the format required for this object
+	 * @param requestBodiesItem
+	 *            a reusable request body object
 	 * @return the current Components object
 	 */
 	Components addRequestBodies(String key, RequestBody requestBodiesItem);
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
index 38057b37f..9356b2412 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java
@@ -22,25 +22,6 @@
  * <p>
  * Allows referencing an external resource for extended documentation.
  * <p>
- * Fixed Fields
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>description</td>
- * <td>String</td>
- * <td>A short description of the target documentation. CommonMark syntax MAY be
- * used for rich text representation.</td>
- * </tr>
- * <tr>
- * <td>url</td>
- * <td>String</td>
- * <td>REQUIRED. The URL for the target documentation. Value MUST be in the format of a URL.</td>
- * </tr>
- * </table>
  * 
  * @see <a href=
  *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#externalDocumentationObject">OpenAPI
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
index 41e415b0c..6a39a12f2 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java
@@ -29,70 +29,12 @@
 /**
  * OpenAPI
  * <p>
- * This is the root document object of the OpenAPI document. It contains the
- * following required and optional fields.
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>openapi</td>
- * <td>string</td>
- * <td>REQUIRED. This string MUST be the semantic version number of the OpenAPI
- * Specification version that the OpenAPI document uses. The openapi field
- * SHOULD be used by tooling specifications and clients to interpret the OpenAPI
- * document. This is not related to the API info.version string.</td>
- * </tr>
- * <tr>
- * <td>info</td>
- * <td>{@link Info Info Object}</td>
- * <td>REQUIRED. Provides metadata about the API. The metadata MAY be used by
- * tooling as required.</td>
- * </tr>
- * <tr>
- * <td>servers</td>
- * <td>[{@link Server Server Object}]</td>
- * <td>An array of Server Objects, which provide connectivity information to a
- * target server. If the servers property is not provided, or is an empty array,
- * the default value would be a Server Object with a url value of /.</td>
- * </tr>
- * <tr>
- * <td>paths</td>
- * <td>{@link Paths Paths Object}</td>
- * <td>REQUIRED. The available paths and operations for the API.</td>
- * </tr>
- * <tr>
- * <td>components</td>
- * <td>{@link Components Components Object}</td>
- * <td>An element to hold various schemas for the specification.</td>
- * </tr>
- * <tr>
- * <td>security</td>
- * <td>[{@link SecurityRequirement SecurityRequirement Object}]</td>
- * <td>A declaration of which security mechanisms can be used across the API.
- * The list of values includes alternative security requirement objects that can
- * be used. Only one of the security requirement objects need to be satisfied to
- * authorize a request. Individual operations can override this definition.</td>
- * </tr>
- * <tr>
- * <td>tags</td>
- * <td>[{@link Tag Tag Object}]</td>
- * <td>A list of tags used by the specification with additional metadata. The
- * order of the tags can be used to reflect on their order by the parsing tools.
- * Not all tags that are used by the Operation Object must be declared. The tags
- * that are not declared MAY be organized randomly or based on the tools' logic.
- * Each tag name in the list MUST be unique.</td>
- * </tr>
- * <tr>
- * <td>externalDocs</td>
- * <td>{@link ExternalDocumentation External Documentation Object}</td>
- * <td>Additional external documentation.</td>
- * </tr>
- * </table>
+ * This is the root document object of the OpenAPI document. It contains
+ * required and optional fields.
  * 
- * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#openapi-object">OpenAPI Specification OpenAPI Object</a>
+ * @see <a href=
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#openapi-object">OpenAPI
+ *      Specification OpenAPI Object</a>
  */
 public interface OpenAPI extends Constructible, Extensible {
 
@@ -233,14 +175,14 @@ public interface OpenAPI extends Constructible, Extensible {
 	/**
 	  * Sets this OpenAPI instance's tags property to the given Tags.
 	  *
-	  * @param tags tags used by the specification
+	  * @param tags tags used by the specification with additional metadata
 	  */
 	void setTags(List<Tag> tags);
 
 	/**
 	  * Sets this OpenAPI instance's tags property to the given tags.
 	  *
-	  * @param tags tags used by the specification
+	  * @param tags tags used by the specification with additional metadata
 	  * @return the current OpenAPI object
 	  */
 	OpenAPI tags(List<Tag> tags);
@@ -248,7 +190,7 @@ public interface OpenAPI extends Constructible, Extensible {
 	/**
 	  * Adds the given tag to this OpenAPI instance's list of tags.
 	  *
-	  * @param tagsItem a tag used by the specification
+	  * @param tagsItem a tag used by the specification with additional metadata
 	  * @return the current OpenAPI object
 	  */
 	OpenAPI addTagsItem(Tag tagsItem);
@@ -294,14 +236,14 @@ public interface OpenAPI extends Constructible, Extensible {
 	/**
 	  * Sets this OpenAPI instance's components property to the given components.
 	  *
-	  * @param components schemas used in the specification
+	  * @param components  a set of reusable objects used in the API specification
 	  */
 	void setComponents(Components components);
 
 	/**
 	  * Sets this OpenAPI instance's components property to the given components.
 	  *
-	  * @param components schemas used in the specification
+	  * @param components  a set of reusable objects used in the API specification
 	  * @return the current OpenAPI object
 	  */
 	OpenAPI components(Components components);
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 da5e6b088..cacc7ec71 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
@@ -32,105 +32,10 @@
  * <p>
  * Describes a single API operation on a path.
  * <p>
- * Fixed Fields
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>tags</td>
- * <td>[string]</td>
- * <td>A list of tags for API documentation control. Tags can be used for
- * logical grouping of operations by resources or any other qualifier.</td>
- * </tr>
- * <tr>
- * <td>summary</td>
- * <td>string</td>
- * <td>A short summary of what the operation does.</td>
- * </tr>
- * <tr>
- * <td>description</td>
- * <td>string</td>
- * <td>A verbose explanation of the operation behavior. CommonMark syntax MAY be
- * used for rich text representation.</td>
- * </tr>
- * <tr>
- * <td>externalDocs</td>
- * <td>{@link ExternalDocumentation External Documentation Object }</td>
- * <td>Additional external documentation for this operation.</td>
- * </tr>
- * <tr>
- * <td>operationId</td>
- * <td>string</td>
- * <td>Unique string used to identify the operation. The id MUST be unique among
- * all operations described in the API. Tools and libraries MAY use the
- * operationId to uniquely identify an operation, therefore, it is RECOMMENDED
- * to follow common programming naming conventions.</td>
- * </tr>
- * <tr>
- * <td>parameters</td>
- * <td>[{@link Parameter Parameter Object } | {@link Parameter Reference Object}]</td>
- * <td>A list of parameters that are applicable for this operation. If a
- * parameter is already defined at the Path Item, the new definition will
- * override it but can never remove it. The list MUST NOT include duplicated
- * parameters. A unique parameter is defined by a combination of a name and
- * location. The list can use the Reference Object to link to parameters that
- * are defined at the OpenAPI Object's components/parameters.</td>
- * </tr>
- * <tr>
- * <td>requestBody</td>
- * <td>{@link RequestBody Request Body Object } | {@link RequestBody Reference
- * Object}</td>
- * <td>The request body applicable for this operation. The requestBody is only
- * supported in HTTP methods where the HTTP 1.1 specification RFC7231 has
- * explicitly defined semantics for request bodies. In other cases where the
- * HTTP spec is vague, requestBody SHALL be ignored by consumers.</td>
- * </tr>
- * <tr>
- * <td>responses</td>
- * <td>{@link ApiResponses Responses Object }</td>
- * <td>REQUIRED. The list of possible responses as they are returned from
- * executing this operation.</td>
- * </tr>
- * <tr>
- * <td>callbacks</td>
- * <td>Map[string, {@link Callback Callback Object } | {@link Callback Reference
- * Object}]</td>
- * <td>A map of possible out-of band callbacks related to the parent operation.
- * The key is a unique identifier for the Callback Object. Each value in the map
- * is a Callback Object that describes a request that may be initiated by the
- * API provider and the expected responses. The key value used to identify the
- * callback object is an expression, evaluated at runtime, that identifies a URL
- * to use for the callback operation.</td>
- * </tr>
- * <tr>
- * <td>deprecated</td>
- * <td>boolean</td>
- * <td>Declares this operation to be deprecated. Consumers SHOULD refrain from
- * usage of the declared operation. Default value is false.</td>
- * </tr>
- * <tr>
- * <td>security</td>
- * <td>[{@link SecurityRequirement Security Requirement Object }]</td>
- * <td>A declaration of which security mechanisms can be used for this
- * operation. The list of values includes alternative security requirement
- * objects that can be used. Only one of the security requirement objects need
- * to be satisfied to authorize a request. This definition overrides any
- * declared top-level security. To remove a top-level security declaration, an
- * empty array can be used.</td>
- * </tr>
- * <tr>
- * <td>servers</td>
- * <td>[{@link Server Server Object }]</td>
- * <td>An alternative server array to service this operation. If an alternative
- * server object is specified at the Path Item Object or Root level, it will be
- * overridden by this value.</td>
- * </tr>
- * </table>
  * 
- * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject">OpenAPI Specification Operation Object</a>
+ * @see <a href=
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject">OpenAPI
+ *      Specification Operation Object</a>
  */
 public interface Operation extends Constructible, Extensible {
 
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
index 058e69801..95ac5b235 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
@@ -26,96 +26,13 @@
 /**
  * PathItem
  * <p>
- * Describes the operations available on a single path. A Path Item MAY be empty
- * due to ACL constraints. In that case the path itself is still exposed to the
+ * Describes the operations available on a single path. A Path Item MAY be
+ * empty, due to <a href=
+ * "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#security-filtering">security
+ * constraints</a>. In that case the path itself is still exposed to the
  * documentation viewer but you will not know which operations and parameters
  * are available.
  * <p>
- * Fixed Fields
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>reference</td>
- * <td>string</td>
- * <td>Allows for an external definition of this path item. The referenced
- * structure MUST be in the format of a Path Item Object. This field represents
- * the $ref field in the OAS file. If there are conflicts between the referenced
- * definition and this Path Item's definition, the behavior is undefined.</td>
- * </tr>
- * <tr>
- * <td>summary</td>
- * <td>string</td>
- * <td>A short summary of what the path item represents and which is intended to
- * apply to all operations in this path.</td>
- * </tr>
- * <tr>
- * <td>description</td>
- * <td>string</td>
- * <td>A detailed description of what the path item represents and which is
- * intended to apply to all operations in this path. CommonMark syntax MAY be
- * used for rich text representation.</td>
- * </tr>
- * <tr>
- * <td>get</td>
- * <td>{@link Operation Operation Object}</td>
- * <td>A definition of a GET operation on this path.</td>
- * </tr>
- * <tr>
- * <td>put</td>
- * <td>{@link Operation Operation Object}</td>
- * <td>A definition of a PUT operation on this path.</td>
- * </tr>
- * <tr>
- * <td>post</td>
- * <td>{@link Operation Operation Object}</td>
- * <td>A definition of a POST operation on this path.</td>
- * </tr>
- * <tr>
- * <td>delete</td>
- * <td>{@link Operation Operation Object}</td>
- * <td>A definition of a DELETE operation on this path.</td>
- * </tr>
- * <tr>
- * <td>options</td>
- * <td>{@link Operation Operation Object}</td>
- * <td>A definition of a OPTIONS operation on this path.</td>
- * </tr>
- * <tr>
- * <td>head</td>
- * <td>{@link Operation Operation Object}</td>
- * <td>A definition of a HEAD operation on this path.</td>
- * </tr>
- * <tr>
- * <td>patch</td>
- * <td>{@link Operation Operation Object}</td>
- * <td>A definition of a PATCH operation on this path.</td>
- * </tr>
- * <tr>
- * <td>trace</td>
- * <td>{@link Operation Operation Object}</td>
- * <td>A definition of a TRACE operation on this path.</td>
- * </tr>
- * <tr>
- * <td>servers</td>
- * <td>[{@link Server Server Object}]</td>
- * <td>An alternative server array to service all operations in this path.</td>
- * </tr>
- * <tr>
- * <td>parameters</td>
- * <td>[{@link Parameter Parameter Object } | {@link Parameter Reference Object
- * }]</td>
- * <td>A list of parameters that are applicable to all the operations described
- * under this path. These parameters can be overridden at the operation level,
- * but cannot be removed there. The list MUST NOT include duplicated parameters.
- * A unique parameter is defined by a combination of a name and location. The
- * list can use the Reference Object to link to parameters that are defined at
- * the OpenAPI Object's components/parameters.</td>
- * </tr>
- * </table>
  * 
  * @see <a href=
  *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathItemObject">
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 251c186ba..b86512492 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
@@ -24,42 +24,27 @@
  * <p>
  * Holds the relative paths to the individual endpoints and their operations.
  * The path is appended to the URL from the Server Object in order to construct
- * the full URL. The Paths MAY be empty, due to ACL constraints.
+ * the full URL. The Paths MAY be empty, due to <a href=
+ * "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#security-filtering">security
+ * constraints</a>.
  * <p>
- * Patterned Fields
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Pattern</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>/{path}</td>
- * <td>{@link PathItem Path Item Object}</td>
- * <td>A relative path to an individual endpoint. The field name MUST begin with
- * a slash. The path is appended (no relative URL resolution) to the expanded
- * URL from the Server Object's url field in order to construct the full URL.
- * Path templating is allowed. When matching URLs, concrete (non-templated)
- * paths would be matched before their templated counterparts. Templated paths
- * with the same hierarchy but different templated names MUST NOT exist as they
- * are identical. In case of ambiguous matching, it's up to the tooling to
- * decide which one to use.</td>
- * </tr>
- * </table>
  * 
- * @see <a
- *      href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathsObject">
+ * @see <a href=
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathsObject">
  *      OpenAPI Specification Paths Object</a>
  */
 public interface Paths extends Constructible, Extensible, Map<String, PathItem> {
 
 	/**
-	  * 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
-	  * @param item the path item added to the list of paths
-	  * @return the current Paths instance
-	  */
+	 * 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
+	 * @return the current Paths instance
+	 */
 	Paths addPathItem(String name, PathItem item);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
index 0d67d9e5e..f512e61a6 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
@@ -25,49 +25,6 @@
  * <p>
  * An object containing sample data for the related object.
  * <p>
- * Fixed Fields
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>reference</td>
- * <td>string</td>
- * <td>Allows for an external definition of this example. The referenced
- * structure MUST be in the format of an Example Object. This field represents
- * the $ref field in the OAS file. If there are conflicts between the referenced
- * definition and this Example's definition, the behavior is undefined.</td>
- * </tr>
- * <tr>
- * <td>summary</td>
- * <td>string</td>
- * <td>Short description for the example.</td>
- * </tr>
- * <tr>
- * <td>description</td>
- * <td>string</td>
- * <td>Long description for the example. CommonMark syntax MAY be used for rich
- * text representation.</td>
- * </tr>
- * <tr>
- * <td>value</td>
- * <td>Any</td>
- * <td>Embedded literal example. The value field and externalValue field are
- * mutually exclusive. To represent examples of media types that cannot
- * naturally be represented in JSON or YAML, use a string value to contain the
- * example, escaping where necessary.</td>
- * </tr>
- * <tr>
- * <td>externalValue</td>
- * <td>string</td>
- * <td>A URL that points to the literal example. This provides the capability to
- * reference examples that cannot easily be included in JSON or YAML documents.
- * The value field and externalValue field are mutually exclusive.</td>
- * </tr>
- * </table>
- * <p>
  * In all cases, the example value is expected to be compatible with the type
  * schema of its associated value. Tooling implementations MAY choose to
  * validate compatibility automatically, and reject the example value(s) if
@@ -132,6 +89,7 @@ public interface Example extends Constructible, Extensible {
 
 	/**
 	 * Sets this Example's value property to the given value.
+	 * The value field and externalValue field are mutually exclusive.
 	 *
 	 * @param value a literal example object
 	 */
@@ -139,6 +97,7 @@ public interface Example extends Constructible, Extensible {
 
 	/**
 	 * Sets this Example's value property to the given value.
+	 * The value field and externalValue field are mutually exclusive.
 	 *
 	 * @param value a literal example object
 	 * @return the current Example object
@@ -154,6 +113,7 @@ public interface Example extends Constructible, Extensible {
 
 	/**
 	 * Sets this Example's externalValue property to the given string.
+	 * The value field and externalValue field are mutually exclusive.
 	 *
 	 * @param externalValue URL that points to the literal example
 	 */
@@ -161,6 +121,7 @@ public interface Example extends Constructible, Extensible {
 
 	/**
 	 * Sets this Example's externalValue property to the given string.
+	 * The value field and externalValue field are mutually exclusive.
 	 *
 	 * @param externalValue URL that points to the literal example
 	 * @return the current Example object
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 f8942c2b1..e255a0866 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
@@ -28,143 +28,12 @@
 /**
  * Header
  * <p>
- * Describes a single operation header parameter.
+ * Describes a single header parameter for an operation.
  * <p>
- * Fixed Fields
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>reference</td>
- * <td>string</td>
- * <td>Allows for an external definition of this header. The referenced
- * structure MUST be in the format of a Header Object. This field represents the
- * $ref field in the OAS file. If there are conflicts between the referenced
- * definition and this Header's definition, the behavior is undefined.</td>
- * </tr>
- * <tr>
- * <td>description</td>
- * <td>string</td>
- * <td>A brief description of the parameter. This could contain examples of use.
- * CommonMark syntax MAY be used for rich text representation.</td>
- * </tr>
- * <tr>
- * <td>required</td>
- * <td>boolean</td>
- * <td>Determines whether this parameter is mandatory. The property MAY be
- * included and its default value is false.</td>
- * </tr>
- * <tr>
- * <td>deprecated</td>
- * <td>boolean</td>
- * <td>Specifies that a parameter is deprecated and SHOULD be transitioned out
- * of usage.</td>
- * </tr>
- * <tr>
- * <td>allowEmptyValue</td>
- * <td>boolean</td>
- * <td>Sets the ability to pass empty-valued parameters. This is valid only for
- * query parameters and allows sending a parameter with an empty value. Default
- * value is false. If style is used, and if behavior is n/a (cannot be
- * serialized), the value of allowEmptyValue SHALL be ignored.</td>
- * </tr>
- * </table>
- * The rules for serialization of the header parameter are specified in one of
- * two ways. For simpler scenarios, a schema and style can describe the
- * structure and syntax of the header parameter.
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>style</td>
- * <td>string</td>
- * <td>Describes how the parameter value will be serialized depending on the
- * type of the parameter value. Default value for header is simple.</td>
- * </tr>
- * <tr>
- * <td>explode</td>
- * <td>boolean</td>
- * <td>When this is true, parameter 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 parameters this property has no effect. When style is
- * form, the default value is true. For all other styles, the default value is
- * false.</td>
- * </tr>
- * <tr>
- * <td>allowReserved</td>
- * <td>boolean</td>
- * <td>Determines whether the parameter value SHOULD allow reserved characters,
- * as defined by RFC3986 <code>:/?#[]@!$&'()*+,;=</code> to be included without
- * percent-encoding. This property only applies to parameters with an in value
- * of query. The default value is false.</td>
- * </tr>
- * <tr>
- * <td>schema</td>
- * <td>{@link Schema Schema Object} | {@link Schema Reference Object}</td>
- * <td>The schema defining the type used for the parameter.</td>
- * </tr>
- * <tr>
- * <td>example</td>
- * <td>Any</td>
- * <td>Example of the media type. The example SHOULD match the specified schema
- * and encoding properties if present. The example object is mutually exclusive
- * of the examples object. Furthermore, if referencing a schema which contains
- * an example, the example value SHALL override the example provided by the
- * schema. To represent examples of media types that cannot naturally be
- * represented in JSON or YAML, a string value can contain the example with
- * escaping where necessary.</td>
- * </tr>
- * <tr>
- * <td>examples</td>
- * <td>Map[ string, {@link Example Example Object} | {@link Example Reference Object}]</td>
- * <td>Examples of the media type. Each example SHOULD contain a value in the
- * correct format as specified in the parameter encoding. The examples object is
- * mutually exclusive of the example object. Furthermore, if referencing a
- * schema which contains an example, the examples value SHALL override the
- * example provided by the schema.</td>
- * </tr>
- * </table>
- * For more complex scenarios, the content property can define the media type
- * and schema of the parameter. A parameter MUST contain either a schema
- * property, or a content property, but not both. When example or examples are
- * provided in conjunction with the schema object, the example MUST follow the
- * prescribed serialization strategy for the parameter.
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>content</td>
- * <td>Map[string, {@link MediaType Media Type Object} ]</td>
- * <td>A map containing the representations for the parameter. The key is the
- * media type and the value describes it. The map MUST only contain one
- * entry.</td>
- * </tr>
- * </table>
- * Style Values
- * <p>
- * For headers only one way of serializing the parameters, simple.
- * <table border=1 cellpadding="8">
- * <tr>
- * <th>Style</th>
- * <th>Type</th>
- * <th>Comments</th>
- * </tr>
- * <tr>
- * <td>simple</td>
- * <td>array</td>
- * <td>Simple style parameters defined by RFC6570. This option replaces
- * collectionFormat with a csv value from OpenAPI 2.0.</td>
- * </tr>
- * </table>
+ * 
+ * @see <a href=
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#header-object">OpenAPI
+ *      Specification Header Object</a>
  */
 public interface Header extends Constructible, Extensible {
 	
@@ -233,21 +102,21 @@ public String toString() {
 	/**
 	 * Returns the deprecated property from a Header instance.
 	 *
-	 * @return  whether a parameter is deprecated
+	 * @return  whether the header parameter is deprecated
 	 **/
 	Boolean getDeprecated();
 
 	/**
 	 * Sets this Header's deprecated property to the given value.
 	 *
-	 * @param deprecated  whether a parameter is deprecated
+	 * @param deprecated  whether the header parameter is deprecated
 	 */
 	void setDeprecated(Boolean deprecated);
 
 	/**
 	 * Sets this Header's deprecated property to the given value.
 	 *
-	 * @param deprecated  whether a parameter is deprecated
+	 * @param deprecated  whether the header parameter is deprecated
 	 * @return the current Header instance
 	 */
 	Header deprecated(Boolean deprecated);
@@ -262,14 +131,14 @@ public String toString() {
 	/**
 	 * Sets this Header's allowEmptyValue property to the given value.
 	 *
-	 * @param allowEmptyValue  the ability to pass empty-valued parameters
+	 * @param allowEmptyValue  specify the ability to pass empty-valued parameters
 	 */
 	void setAllowEmptyValue(Boolean allowEmptyValue);
 
 	/**
 	 * Sets this Header's allowEmptyValue property to the given value.
 	 *
-	 * @param allowEmptyValue  the ability to pass empty-valued parameters
+	 * @param allowEmptyValue  specify the ability to pass empty-valued parameters
 	 * @return the current Header instance
 	 */
 	Header allowEmptyValue(Boolean allowEmptyValue);
@@ -299,21 +168,26 @@ public String toString() {
 	/**
 	 * Returns the explode property from a Header instance.
 	 *
-	 * @return whether parameter values of type "array" or "object" generate separate parameters for each value
+	 * @return whether parameter values of type "array" or "object" generate
+	 *         separate parameters for each value
 	 **/
 	Boolean getExplode();
 
 	/**
 	 * Sets this Header's explode property to the given value.
 	 *
-	 * @param explode  whether parameter values of type "array" or "object" generate separate parameters for each value
+	 * @param explode
+	 *            whether parameter values of type "array" or "object" generate
+	 *            separate parameters for each value
 	 */
 	void setExplode(Boolean explode);
 
 	/**
 	 * Sets this Header's explode property to the given value.
 	 *
-	 * @param explode  whether parameter values of type "array" or "object" generate separate parameters for each value
+	 * @param explode
+	 *            whether parameter values of type "array" or "object" generate
+	 *            separate parameters for each value
 	 * @return the current Header instance
 	 */
 	Header explode(Boolean explode);
@@ -321,21 +195,21 @@ public String toString() {
 	/**
 	 * Returns the schema property from a Header instance.
 	 *
-	 * @return schema defining the type used for the parameter
+	 * @return schema defining the type used for the header parameter
 	 **/
 	Schema getSchema();
 
 	/**
 	 * Sets this Header's schema property to the given object.
 	 *
-	 * @param schema  schema defining the type used for the parameter
+	 * @param schema  schema defining the type used for the header parameter
 	 */
 	void setSchema(Schema schema);
 
 	/**
 	 * Sets this Header's schema property to the given object.
 	 *
-	 * @param schema  schema defining the type used for the parameter
+	 * @param schema  schema defining the type used for the header parameter
 	 * @return the current Header instance
 	 */
 	Header schema(Schema schema);
@@ -349,6 +223,8 @@ public String toString() {
 
 	/**
 	 * Sets the examples property of this Header instance to the given map.
+	 * Each example should contain a value in the correct format as specified in the parameter encoding.
+	 * The examples object is mutually exclusive of the example object.
 	 *
 	 * @param examples  examples of the media type
 	 */
@@ -356,6 +232,8 @@ public String toString() {
 
 	/**
 	 * Sets the examples property of this Header instance to the given map.
+	 * Each example should contain a value in the correct format as specified in the parameter encoding.
+	 * The examples object is mutually exclusive of the example object.
 	 *
 	 * @param examples  examples of the media type
 	 * @return the current Header instance 
@@ -363,7 +241,8 @@ public String toString() {
 	Header examples(Map<String, Example> examples);
 
 	/**
-	 * Adds an example of the media type using the specified key.
+	 * Adds an example of the media type using the specified key to this Header instance.
+	 * The example should contain a value in the correct format as specified in the parameter encoding.
 	 *
 	 * @param key string to represent the example
 	 * @param examplesItem  example of the media type
@@ -380,6 +259,8 @@ public String toString() {
 
 	/**
 	 * Sets this Header's example property to the given object.
+	 * The example should match the specified schema and encoding properties if present.
+	 * The examples object is mutually exclusive of the example object.
 	 *
 	 * @param example  example of the media type
 	 */
@@ -387,6 +268,8 @@ public String toString() {
 
 	/**
 	 * Sets this Header's example property to the given object.
+	 * The example should match the specified schema and encoding properties if present.
+	 * The examples object is mutually exclusive of the example object.
 	 *
 	 * @param example  example of the media type
 	 * @return the current Header instance
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 8ef6e9b22..4e59d42e0 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
@@ -32,71 +32,10 @@
  * invoke it, rather it provides a known relationship and traversal mechanism
  * between responses and other operations.
  * <p>
- * Unlike dynamic links (i.e. links provided in the response payload), the OAS
- * linking mechanism does not require link information in the runtime response.
- * <p>
  * For computing links, and providing instructions to execute them, a runtime
  * expression is used for accessing values in an operation and using them as
  * parameters while invoking the linked operation.
  * <p>
- * Fixed Fields
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>reference</td>
- * <td>string</td>
- * <td>Allows for an external definition of this link. The referenced structure
- * MUST be in the format of a Link Object. This field represents the $ref field
- * in the OAS file. If there are conflicts between the referenced definition and
- * this Link's definition, the behavior is undefined.</td>
- * </tr>
- * <tr>
- * <td>operationRef</td>
- * <td>string</td>
- * <td>A relative or absolute reference to an OAS operation. This field is
- * mutually exclusive of the operationId field, and MUST point to an Operation
- * Object. Relative operationRef values MAY be used to locate an existing
- * Operation Object in the OpenAPI definition.</td>
- * </tr>
- * <tr>
- * <td>operationId</td>
- * <td>string</td>
- * <td>The name of an existing, resolvable OAS operation, as defined with a
- * unique operationId. This field is mutually exclusive of the operationRef
- * field.</td>
- * </tr>
- * <tr>
- * <td>parameters</td>
- * <td>Map[string, Any | {expression}]</td>
- * <td>A map representing parameters to pass to an operation as specified with
- * operationId or identified via operationRef. The key is the parameter name to
- * be used, whereas the value can be a constant or an expression to be evaluated
- * and passed to the linked operation. The parameter name can be qualified using
- * the parameter location [{in}.]{name} for operations that use the same
- * parameter name in different locations (e.g. path.id).</td>
- * </tr>
- * <tr>
- * <td>requestBody</td>
- * <td>{@link RequestBody Request Body Object} | runtime expression</td>
- * <td>A literal value or runtime expression to use as a request body when
- * calling the target operation.</td>
- * </tr>
- * <tr>
- * <td>description</td>
- * <td>string</td>
- * <td>A description of the link. CommonMark syntax MAY be used for rich text
- * representation.</td>
- * </tr>
- * <tr>
- * <td>server</td>
- * <td>{@link Server Server Object}</td>
- * <td>A server object to be used by the target operation.</td>
- * </tr>
- * </table>
  * A linked operation MUST be identified using either an operationRef or
  * operationId. In the case of an operationId, it MUST be unique and resolved in
  * the scope of the OAS document. Because of the potential for name clashes, the
@@ -127,7 +66,7 @@ public interface Link extends Constructible, Extensible {
 	 * Sets this Link's server property to the given object.
 	 *
 	 * @param server  a server object to be used by the target operation
-	 * @return the current instance of Link
+	 * @return the current Link instance
 	 */
 	Link server(Server server);
 
@@ -140,6 +79,7 @@ public interface Link extends Constructible, Extensible {
 
 	/**
 	 * Sets this Link's operationRef property to the given string.
+	 * This field is mutually exclusive of the operationId field.
 	 *
 	 * @param operationRef  a relative or absolute reference to an OAS operation
 	 */
@@ -147,43 +87,50 @@ public interface Link extends Constructible, Extensible {
 
 	/**
 	 * Sets this Link's operationRef property to the given string.
+	 * This field is mutually exclusive of the operationId field.
 	 *
 	 * @param operationRef  a relative or absolute reference to an OAS operation
-	 * @return the current instance of Link
+	 * @return the current Link instance
 	 */
 	Link operationRef(String operationRef);
 
 	/**
 	 * Returns the requestBody property from a Link instance.
 	 *
-	 * @return a literal value or runtime expression to use as a request body when calling the target operation
+	 * @return a literal value or runtime expression to use as a request body
+	 *         when calling the target operation
 	 **/
 	RequestBody getRequestBody();
 
 	/**
 	 * Sets this Link's requestBody property to the given object.
 	 *
-	 * @param requestBody  a literal value or runtime expression to use as a request body when calling the target operation
+	 * @param requestBody
+	 *            a literal value or runtime expression to use as a request body
+	 *            when calling the target operation
 	 */
 	void setRequestBody(RequestBody requestBody);
 
 	/**
 	 * Sets this Link's requestBody property to the given object.
 	 *
-	 * @param requestBody  a literal value or runtime expression to use as a request body when calling the target operation
-	 * @return the current instance of Link
+	 * @param requestBody
+	 *            a literal value or runtime expression to use as a request body
+	 *            when calling the target operation
+	 * @return the current Link instance
 	 */
 	Link requestBody(RequestBody requestBody);
 
 	/**
 	 * Returns the operationId property for this instance of Link.
 	 *
-	 * @param operationId  the name of an existing, resolvable OAS operation
+	 * @return  the name of an existing, resolvable OAS operation
 	 */
 	String getOperationId();
 
 	/**
 	 * Sets this Link's operationId property to the given string.
+	 * This field is mutually exclusive of the operationRef field.
 	 *
 	 * @param operationId  the name of an existing, resolvable OAS operation
 	 */
@@ -191,14 +138,17 @@ public interface Link extends Constructible, Extensible {
 
 	/**
 	 * Sets this Link's operationId property to the given string.
+	 * This field is mutually exclusive of the operationRef field.
 	 *
 	 * @param operationId  the name of an existing, resolvable OAS operation
-	 * @return the current instance of Link
+	 * @return the current Link instance
 	 */
 	Link operationId(String operationId);
 
 	/**
 	 * Returns the parameters property from this instance of Link.
+	 * The key is the parameter name and the value is a constant or a 
+	 * runtime expression to be passed to the linked operation.
 	 *
 	 * @return a map representing parameters to pass to this link's operation
 	 **/
@@ -207,16 +157,23 @@ public interface Link extends Constructible, Extensible {
 	/**
 	 * Sets this Link's parameters property to the given map.
 	 *
-	 * @param parameters  a map representing parameters to pass to this link's operation
+	 * @param parameters
+	 *            a map representing parameters to pass to this link's operation
+	 *            as specified with operationId or identified via operationRef
 	 */
 	void setParameters(Map<String, String> parameters);
 
 	/**
-	 * Add a new parameter to the parameters property of this instance of Link. 
+	 * Add a new parameter to the parameters property of this instance of 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
-	 * @return the current instance of 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
+	 * @return the current Link instance
 	 */
 	Link parameters(String name, String parameter);
 
@@ -238,7 +195,7 @@ public interface Link extends Constructible, Extensible {
 	 * Sets this Link's description property to the given string.
 	 *
 	 * @param description  a description of the link
-	 * @return the current instance of Link
+	 * @return the current Link instance
 	 */
 	Link description(String description);
 
@@ -260,7 +217,7 @@ public interface Link extends Constructible, Extensible {
 	 * Sets this Link's reference property to the given string.
 	 *
 	 * @param reference  a reference to a link object in the components in this OpenAPI document
-	 * @return the current instance of Link
+	 * @return the current Link instance
 	 */
 	Link reference(String reference);
 
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 18a1c120f..631e02394 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
@@ -30,28 +30,6 @@
  * schema which is used to inform the consumer of the specification of an
  * alternative schema based on the value associated with it.
  * <p>
- * When using the discriminator, inline schemas will not be considered.
- * <p>
- * Fixed Fields
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>propertyName</td>
- * <td>string</td>
- * <td>REQUIRED. The name of the property in the payload that will hold the
- * discriminator value.</td>
- * </tr>
- * <tr>
- * <td>mapping</td>
- * <td>Map[string, string]</td>
- * <td>An object to hold mappings between payload values and schema names or
- * references.</td>
- * </tr>
- * </table>
  * 
  * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#discriminator-object">OpenAPI Specification Discriminator Object</a>
  */
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 654d6b887..1c13469c2 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
@@ -29,45 +29,6 @@
  * Each Media Type Object provides a schema and examples for the media type
  * identified by its key.
  * <p>
- * Fixed Fields
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>schema</td>
- * <td>{@link Schema Schema Object} | {@link Schema Reference Object}</td>
- * <td>The schema defining the type used for the request body.</td>
- * </tr>
- * <tr>
- * <td>example</td>
- * <td>Any</td>
- * <td>Example of the media type. The example object SHOULD be in the correct
- * format as specified by the media type. The example object is mutually
- * exclusive of the examples object. Furthermore, if referencing a schema which
- * contains an example, the example value SHALL override the example provided by
- * the schema.</td>
- * </tr>
- * <tr>
- * <td>examples</td>
- * <td>Map[ string, {@link Example Example Object} | {@link Example Reference Object}]</td>
- * <td>Examples of the media type. Each example object SHOULD match the media
- * type and specified schema if present. The examples object is mutually
- * exclusive of the example object. Furthermore, if referencing a schema which
- * contains an example, the examples value SHALL override the example provided
- * by the schema.</td>
- * </tr>
- * <tr>
- * <td>encoding</td>
- * <td>Map[string, {@link Encoding Encoding Object}]</td>
- * <td>A map between a property name and its encoding information. The key,
- * being the property name, MUST exist in the schema as a property. The encoding
- * object SHALL only apply to requestBody objects when the media type is
- * multipart or application/x-www-form-urlencoded.</td>
- * </tr>
- * </table>
  * 
  * @see <a
  *      href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#mediaTypeObject">OpenAPI
@@ -107,6 +68,8 @@ public interface MediaType extends Constructible, Extensible {
 
 	/**
 	 * Sets the examples field of a MediaType instance to the given map object.
+	 * Each example object should match the media type and specified schema if present.
+	 * The example object is mutually exclusive of the examples object.
 	 *
 	 * @param examples  examples of the media type
 	 */
@@ -114,6 +77,8 @@ public interface MediaType extends Constructible, Extensible {
 
 	/**
 	 * Sets the examples field of a MediaType instance to the given map object.
+	 * Each example object should match the media type and specified schema if present.
+	 * The example object is mutually exclusive of the examples object.
 	 *
 	 * @param examples  examples of the media type
 	 * @return the current MediaType instance
@@ -122,6 +87,7 @@ public interface MediaType extends Constructible, Extensible {
 
 	/**
 	 * Adds an example item to the examples map of a MediaType instance.
+	 * The example object should match the media type and specified schema if present.
 	 *
 	 * @param key  any unique name to identify the example object
 	 * @param examplesItem  an example of a media type
@@ -138,6 +104,8 @@ public interface MediaType extends Constructible, Extensible {
 
 	/**
 	 * Sets the example property of a MediaType instance to the given value.
+	 * The example object should be in the correct format as specified by the media type.
+	 * The example object is mutually exclusive of the examples object.
 	 *
 	 * @param example  an example of the media type
 	 */
@@ -145,6 +113,8 @@ public interface MediaType extends Constructible, Extensible {
 
 	/**
 	 * Sets the example property of a MediaType instance to the given value.
+	 * The example object should be in the correct format as specified by the media type.
+	 * The example object is mutually exclusive of the examples object.
 	 *
 	 * @param example  an example of the media type
 	 * @return the current MediaType instance
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 03fb708cf..08f8298ed 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
@@ -21,7 +21,6 @@
 
 import org.eclipse.microprofile.openapi.models.Extensible;
 import org.eclipse.microprofile.openapi.models.examples.Example;
-import org.eclipse.microprofile.openapi.models.media.MediaType;
 import org.eclipse.microprofile.openapi.models.media.Content;
 import org.eclipse.microprofile.openapi.models.media.Schema;
 
@@ -31,9 +30,6 @@
  * Describes a single operation parameter.
  * <p>
  * A unique parameter is defined by a combination of a name and location.
- * <p>
- * Parameter Locations
- * <p>
  * There are four possible parameter locations specified by the in field:
  * <ul>
  * <li>path - Used together with Path Templating, where the parameter value is
@@ -47,207 +43,13 @@
  * <li>cookie - Used to pass a specific cookie value to the API.</li>
  * </ul>
  * <p>
- * Fixed Fields
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>reference</td>
- * <td>string</td>
- * <td>Allows for an external definition of this parameter. The referenced
- * structure MUST be in the format of a Parameter Object. This field represents
- * the $ref field in the OAS file. If there are conflicts between the referenced
- * definition and this Parameter's definition, the behavior is undefined.</td>
- * </tr>
- * <tr>
- * <td>name</td>
- * <td>string</td>
- * <td>REQUIRED. The name of the parameter. Parameter names are case sensitive.
- * <ul>
- * <li>If in is "path", the name field MUST correspond to the associated path
- * segment from the path field in the Paths Object. See Path Templating for
- * further information.</li>
- * <li>If in is "header" and the name field is "Accept", "Content-Type" or
- * "Authorization", the parameter definition SHALL be ignored.</li>
- * <li>For all other cases, the name corresponds to the parameter name used by
- * the in property.</li></ul></td>
- * </tr>
- * <tr>
- * <td>in</td>
- * <td>string</td>
- * <td>REQUIRED. The location of the parameter. Possible values are "query",
- * "header", "path" or "cookie".</td>
- * </tr>
- * <tr>
- * <td>description</td>
- * <td>string</td>
- * <td>A brief description of the parameter. This could contain examples of use.
- * CommonMark syntax MAY be used for rich text representation.</td>
- * </tr>
- * <tr>
- * <td>required</td>
- * <td>boolean</td>
- * <td>Determines whether this parameter is mandatory. If the parameter location
- * is "path", this property is REQUIRED and its value MUST be true. Otherwise,
- * the property MAY be included and its default value is false.</td>
- * </tr>
- * <tr>
- * <td>deprecated</td>
- * <td>boolean</td>
- * <td>Specifies that a parameter is deprecated and SHOULD be transitioned out
- * of usage.</td>
- * </tr>
- * <tr>
- * <td>allowEmptyValue</td>
- * <td>boolean</td>
- * <td>Sets the ability to pass empty-valued parameters. This is valid only for
- * query parameters and allows sending a parameter with an empty value. Default
- * value is false. If style is used, and if behavior is n/a (cannot be
- * serialized), the value of allowEmptyValue SHALL be ignored.</td>
- * </tr>
- * </table>
  * The rules for serialization of the parameter are specified in one of two
  * ways. For simpler scenarios, a schema and style can describe the structure
  * and syntax of the parameter.
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>style</td>
- * <td>string</td>
- * <td>Describes how the parameter value will be serialized depending on the
- * type of the parameter value. Default values (based on value of in): for query
- * - form; for path - simple; for header - simple; for cookie - form.</td>
- * </tr>
- * <tr>
- * <td>explode</td>
- * <td>boolean</td>
- * <td>When this is true, parameter 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 parameters this property has no effect. When style is
- * form, the default value is true. For all other styles, the default value is
- * false.</td>
- * </tr>
- * <tr>
- * <td>allowReserved</td>
- * <td>boolean</td>
- * <td>Determines whether the parameter value SHOULD allow reserved characters,
- * as defined by RFC3986 <code>:/?#[]@!$&'()*+,;=</code> to be included without
- * percent-encoding. This property only applies to parameters with an in value
- * of query. The default value is false.</td>
- * </tr>
- * <tr>
- * <td>schema</td>
- * <td>{@link Schema Schema Object} | {@link Schema Reference Object}</td>
- * <td>The schema defining the type used for the parameter.</td>
- * </tr>
- * <tr>
- * <td>example</td>
- * <td>Any</td>
- * <td>Example of the media type. The example SHOULD match the specified schema
- * and encoding properties if present. The example object is mutually exclusive
- * of the examples object. Furthermore, if referencing a schema which contains
- * an example, the example value SHALL override the example provided by the
- * schema. To represent examples of media types that cannot naturally be
- * represented in JSON or YAML, a string value can contain the example with
- * escaping where necessary.</td>
- * </tr>
- * <tr>
- * <td>examples</td>
- * <td>Map[ string, {@link Example Example Object} | {@link Example Reference
- * Object}]</td>
- * <td>Examples of the media type. Each example SHOULD contain a value in the
- * correct format as specified in the parameter encoding. The examples object is
- * mutually exclusive of the example object. Furthermore, if referencing a
- * schema which contains an example, the examples value SHALL override the
- * example provided by the schema.</td>
- * </tr>
- * </table>
- * For more complex scenarios, the content property can define the media type
- * and schema of the parameter. A parameter MUST contain either a schema
- * property, or a content property, but not both. When example or examples are
- * provided in conjunction with the schema object, the example MUST follow the
- * prescribed serialization strategy for the parameter.
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <tr>
- * <td>content</td>
- * <td>Map[string, {@link MediaType Media Type Object} ]</td>
- * <td>A map containing the representations for the parameter. The key is the
- * media type and the value describes it. The map MUST only contain one
- * entry.</td>
- * </tr>
- * </table>
- * Style Values
  * <p>
- * In order to support common ways of serializing simple parameters, a set of
- * style values are defined.
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Style</th>
- * <th>Type</th>
- * <th>In</th>
- * <th>Comments</th>
- * </tr>
- * <tr>
- * <td>matrix</td>
- * <td>primitive, array, object</td>
- * <td>path</td>
- * <td>Path-style parameters defined by RFC6570</td>
- * </tr>
- * <tr>
- * <td>label</td>
- * <td>primitive, array, object</td>
- * <td>path</td>
- * <td>Label style parameters defined by RFC6570</td>
- * </tr>
- * <tr>
- * <td>form</td>
- * <td>primitive, array, object</td>
- * <td>query, cookie</td>
- * <td>Form style parameters defined by RFC6570. This option replaces
- * collectionFormat with a csv (when explode is false) or multi (when explode is
- * true) value from OpenAPI 2.0.</td>
- * </tr>
- * <tr>
- * <td>simple</td>
- * <td>array</td>
- * <td>path, header</td>
- * <td>Simple style parameters defined by RFC6570. This option replaces
- * collectionFormat with a csv value from OpenAPI 2.0.</td>
- * </tr>
- * <tr>
- * <td>spaceDelimited</td>
- * <td>array</td>
- * <td>query</td>
- * <td>Space separated array values. This option replaces collectionFormat equal
- * to ssv from OpenAPI 2.0.</td>
- * </tr>
- * <tr>
- * <td>pipeDelimited</td>
- * <td>array</td>
- * <td>query</td>
- * <td>Pipe separated array values. This option replaces collectionFormat equal
- * to pipes from OpenAPI 2.0.</td>
- * </tr>
- * <tr>
- * <td>deepObject</td>
- * <td>object</td>
- * <td>query</td>
- * <td>Provides a simple way of rendering nested objects using form
- * parameters.</td>
- * </tr>
- * </table>
+ * For more complex scenarios, the content property can define the media type
+ * and schema of the parameter. A parameter must contain either a schema
+ * property, or a content property, but not both.
  * 
  * @see <a href=
  *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameterObject">OpenAPI
@@ -405,14 +207,14 @@ public String toString() {
 	/**
 	 * Sets the allowEmptyValue property of a Parameter instance to the given value.
 	 *
-	 * @param allowEmptyValue  specifies the ability to pass empty-valued parameters
+	 * @param allowEmptyValue  specify the ability to pass empty-valued parameters
 	 */
 	void setAllowEmptyValue(Boolean allowEmptyValue);
 
 	/**
 	 * Sets the allowEmptyValue property of a Parameter instance to the given value.
 	 *
-	 * @param allowEmptyValue  specifies the ability to pass empty-valued parameters
+	 * @param allowEmptyValue  specify the ability to pass empty-valued parameters
 	 * @return the current Parameter instance
 	 */
 	Parameter allowEmptyValue(Boolean allowEmptyValue);
@@ -442,21 +244,26 @@ public String toString() {
 	/**
 	 * Returns the explode property from a Parameter instance.
 	 *
-	 * @return whether parameter values of type "array" or "object" generate separate parameters for each value
+	 * @return whether parameter values of type "array" or "object" generate
+	 *         separate parameters for each value
 	 **/
 	Boolean getExplode();
 
 	/**
 	 * Sets the explode property of a Parameter instance to the given value.
 	 *
-	 * @param explode  whether parameter values of type "array" or "object" generate separate parameters for each value
+	 * @param explode
+	 *            whether parameter values of type "array" or "object" generate
+	 *            separate parameters for each value
 	 */
 	void setExplode(Boolean explode);
 
 	/**
 	 * Sets the explode property of a Parameter instance to the given value.
 	 *
-	 * @param explode  whether parameter values of type "array" or "object" generate separate parameters for each value
+	 * @param explode
+	 *            whether parameter values of type "array" or "object" generate
+	 *            separate parameters for each value
 	 * @return the current Parameter instance
 	 */
 	Parameter explode(Boolean explode);
@@ -514,6 +321,8 @@ public String toString() {
 
 	/**
 	 * Sets the examples property of a Parameter instance to the given value.
+	 * Each example should contain a value in the correct format as specified in the parameter encoding.
+	 * The examples object is mutually exclusive of the example object.
 	 *
 	 * @param examples  examples of the media type
 	 */
@@ -521,6 +330,8 @@ public String toString() {
 
 	/**
 	 * Sets the examples property of a Parameter instance to the given value.
+	 * Each example should contain a value in the correct format as specified in the parameter encoding.
+	 * The examples object is mutually exclusive of the example object.
 	 *
 	 * @param examples  examples of the media type
 	 * @return the current Parameter instance
@@ -529,6 +340,7 @@ public String toString() {
 
 	/**
 	 * Adds an example of the media type using the specified key.
+	 * The example should contain a value in the correct format as specified in the parameter encoding.
 	 *
 	 * @param key string to represent the example
 	 * @param examplesItem  example of the media type
@@ -545,6 +357,8 @@ public String toString() {
 
 	/**
 	 * Sets the example property of a Parameter instance to the given object.
+	 * The example should match the specified schema and encoding properties if present.
+	 * The examples object is mutually exclusive of the example object.
 	 *
 	 * @param example  example of the media type
 	 */
@@ -552,6 +366,8 @@ public String toString() {
 
 	/**
 	 * Sets the example property of a Parameter instance to the given object.
+	 * The example should match the specified schema and encoding properties if present.
+	 * The examples object is mutually exclusive of the example object.
 	 *
 	 * @param example  example of the media type
 	 * @return the current Parameter instance
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
index 0db6512f4..285c9deea 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java
@@ -25,30 +25,6 @@
  * Tag
  * <p>
  * An object to store metadata to be available in the OpenAPI document. 
- * <p>
- * Fixed Fields
- * <table border=1 cellpadding="8" style="border-collapse: collapse">
- * <tr>
- * <th>Field Name</th>
- * <th>Type</th>
- * <th>Description</th>
- * </tr>
- * <td>name</td>
- * <td>string</td>
- * <td>REQUIRED. The name of the tag.</td>
- * </tr>
- * <tr>
- * <td>description</td>
- * <td>string</td>
- * <td>A short description for the tag. CommonMark syntax MAY be used for rich
- * text representation.</td>
- * </tr>
- * <tr>
- * <td>externalDocs</td>
- * <td>{@link ExternalDocumentation External Documentation Object}</td>
- * <td>Additional external documentation for this tag.</td>
- * </tr>
- * </table>
  * 
  * @see <a href=
  *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#tagObject">OpenAPI

From 070a9656edf861155449aa7a9694caf631d0f81e Mon Sep 17 00:00:00 2001
From: Paul Gooderham <turkeyonmarblerye@gmail.com>
Date: Mon, 30 Oct 2017 15:58:37 -0400
Subject: [PATCH 22/23] Update the Javadoc in the schema classes. Remove field
 name methods from Schema.java 8908

Signed-off-by: Paul Gooderham <turkeyonmarblerye@gmail.com>
---
 .../openapi/models/media/ArraySchema.java     |  30 +-
 .../openapi/models/media/BinarySchema.java    |  64 +-
 .../openapi/models/media/BooleanSchema.java   |  50 +-
 .../openapi/models/media/ByteArraySchema.java |  64 +-
 .../openapi/models/media/ComposedSchema.java  | 118 ++-
 .../openapi/models/media/DateSchema.java      |  64 +-
 .../openapi/models/media/EmailSchema.java     |  65 +-
 .../openapi/models/media/FileSchema.java      |  20 +-
 .../openapi/models/media/IntegerSchema.java   |  64 +-
 .../openapi/models/media/MapSchema.java       |  11 +-
 .../openapi/models/media/NumberSchema.java    |  49 +-
 .../openapi/models/media/ObjectSchema.java    |  11 +-
 .../openapi/models/media/PasswordSchema.java  |  58 +-
 .../openapi/models/media/Schema.java          | 704 ++++++++----------
 .../openapi/models/media/StringSchema.java    |  53 +-
 .../openapi/models/media/UUIDSchema.java      |  79 +-
 16 files changed, 684 insertions(+), 820 deletions(-)

diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ArraySchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ArraySchema.java
index 8c0dd5737..9c9da3600 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ArraySchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ArraySchema.java
@@ -18,32 +18,30 @@
 package org.eclipse.microprofile.openapi.models.media;
 
 /**
- * ArraySchema
+ * The schema used for the elements of an array. All elements must be the same type.
  */
 public interface ArraySchema extends Schema {
 
 	/**
-	   * returns the items property from a ArraySchema instance.
-	   *
-	   * @return Schema items
-	   **/
-
+	 * Returns the schema used for all the elements of an ArraySchema instance (array).
+	 *
+	 * @return the schema used for all the elements
+	 **/
 	Schema getItems();
 
 	/**
-	   * sets this ArraySchema's items property to the given items.
-	   *
-	   * @param SchemaImpl items
-	   */
+	 * Set the schema used for all the elements of an ArraySchema instance (array).
+	 *
+	 * @param items  the schema used by this array
+	 */
 	void setItems(Schema items);
 
 	/**
-	   * sets this ArraySchema's items property to the given items and
-	   * returns this instance of ArraySchema
-	   *
-	   * @param SchemaImpl items
-	   * @return ArraySchema
-	   */
+	 * Set the schema used for all the elements of an ArraySchema instance (array).
+	 *
+	 * @param items  the schema used by this array
+	 * @return the current ArraySchema instance
+	 */
 	ArraySchema items(Schema items);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/BinarySchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/BinarySchema.java
index 4ca083a08..80b2a7735 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/BinarySchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/BinarySchema.java
@@ -20,49 +20,53 @@
 import java.util.List;
 
 /**
- * BinarySchema
+ * The schema used for an object that holds binary data.
  */
 public interface BinarySchema extends Schema<byte[]> {
 
 	/**
-	   * sets this BinarySchema's type property to the given type and
-	   * returns this instance of BinarySchema
-	   *
-	   * @param String type
-	   * @return BinarySchema
-	   */
+	 * Change this BinarySchema's type property from the default value to the
+	 * given string. 
+	 *
+	 * @param type  the name of a valid type
+	 * @return the current BinarySchema instance
+	 */
 	BinarySchema type(String type);
 
 	/**
-	   * sets this BinarySchema's format property to the given format and
-	   * returns this instance of BinarySchema
-	   *
-	   * @param String format
-	   * @return BinarySchema
-	   */
+	 * Change this BinarySchema's format property from the default value to the
+	 * given format. The value may be one of the formats described in the OAS or
+	 * a user defined format.
+	 *
+	 * @param format
+	 *            the string specifying the data format
+	 * @return the current BinarySchema instance
+	 */
 	BinarySchema format(String format);
 
 	/**
-	   * sets the _default property of this BinarySchema to the given _default value.
-	   * 
-	   * @param byte[] _default
-	   * @return BinarySchema
-	   */
-	BinarySchema _default(byte[] _default);
+	 * Sets the default property of this BinarySchema to the given default value.
+	 * 
+	 * @param defaultValue  a value to use as the default
+	 * @return the current BinarySchema instance
+	 */
+	BinarySchema defaultValue(byte[] defaultValue);
 
 	/**
-	   * sets the _enum property of this BinarySchema to the given _enum value.
-	   * 
-	   * @param List&lt;byte[]&gt; _enum
-	   * @return BinarySchema
-	   */
-	BinarySchema _enum(List<byte[]> _enum);
+	 * Sets the enumerated list of values allowed for objects defined by this schema.
+	 *
+	 * @param enumeration a list of values allowed
+	 * @return the current BinarySchema instance
+	 */
+	BinarySchema enumeration(List<byte[]> enumeration);
 
 	/**
-	   * Adds the given _enumItem to this BinarySchema's List of _enumItems.
-	   *
-	   * @param byte[] _enumItem
-	   */
-	BinarySchema addEnumItem(byte[] _enumItem);
+	 * Adds an item of the appropriate type to the enumerated list of values
+	 * allowed.
+	 *
+	 * @param enumerationItem  an object to add to the enumerated values
+	 * @return the current BinarySchema instance
+	 */
+	BinarySchema addEnumerationItem(byte[] enumerationItem);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/BooleanSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/BooleanSchema.java
index 147137fe8..7bc06dbf3 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/BooleanSchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/BooleanSchema.java
@@ -20,40 +20,42 @@
 import java.util.List;
 
 /**
- * BooleanSchema
+ * The schema used for an object that holds boolean data.
  */
 public interface BooleanSchema extends Schema<Boolean> {
 
 	/**
-	   * sets this BooleanSchema's type property to the given type and
-	   * returns this instance of BooleanSchema
-	   *
-	   * @param String type
-	   * @return BooleanSchema
-	   */
+	 * Change this BooleanSchema's type property from the default value to the
+	 * given string. 
+	 *
+	 * @param type  the name of a valid type
+	 * @return the current BooleanSchema instance
+	 */
 	BooleanSchema type(String type);
 
 	/**
-	   * sets the _default property of this BooleanSchema to the given _default value.
-	   * 
-	   * @param byte[] _default
-	   * @return BooleanSchema
-	   */
-	BooleanSchema _default(Boolean _default);
+	 * Sets the default property of this BooleanSchema to the given default value.
+	 * 
+	 * @param defaultValue  a value to use as the default
+	 * @return the current BooleanSchema instance
+	 */
+	BooleanSchema defaultValue(Boolean defaultValue);
 
 	/**
-	   * sets the _enum property of this BooleanSchema to the given _enum value.
-	   * 
-	   * @param List&lt;byte[]&gt; _enum
-	   * @return BooleanSchema
-	   */
-	BooleanSchema _enum(List<Boolean> _enum);
+	 * Sets the enumerated list of values allowed for objects defined by this schema.
+	 *
+	 * @param enumeration a list of values allowed
+	 * @return the current BooleanSchema instance
+	 */
+	BooleanSchema enumeration(List<Boolean> enumeration);
 
 	/**
-	   * Adds the given _enumItem to this BooleanSchema's List of _enumItems.
-	   *
-	   * @param byte[] _enumItem
-	   */
-	BooleanSchema addEnumItem(Boolean _enumItem);
+	 * Adds an item of the appropriate type to the enumerated list of values
+	 * allowed.
+	 *
+	 * @param enumerationItem  an object to add to the enumerated values
+	 * @return the current BooleanSchema instance
+	 */
+	BooleanSchema addEnumerationItem(Boolean enumerationItem);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ByteArraySchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ByteArraySchema.java
index d2f6ff6f1..00de0ce96 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ByteArraySchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ByteArraySchema.java
@@ -20,49 +20,53 @@
 import java.util.List;
 
 /**
- * ByteArraySchema
+ * The schema used for an object that holds an array of byte data.
  */
 public interface ByteArraySchema extends Schema<byte[]> {
 
 	/**
-	   * sets this ByteArraySchema's type property to the given type and
-	   * returns this instance of ByteArraySchema
-	   *
-	   * @param String type
-	   * @return ByteArraySchema
-	   */
+	 * Change this ByteArraySchema's type property from the default value to the
+	 * given string. 
+	 *
+	 * @param type  the name of a valid type
+	 * @return the current ByteArraySchema instance
+	 */
 	ByteArraySchema type(String type);
 
 	/**
-	   * sets this ByteArraySchema's format property to the given format and
-	   * returns this instance of ByteArraySchema
-	   *
-	   * @param String format
-	   * @return ByteArraySchema
-	   */
+	 * Change this ByteArraySchema's format property from the default value to the
+	 * given format. The value may be one of the formats described in the OAS or
+	 * a user defined format.
+	 *
+	 * @param format
+	 *            the string specifying the data format
+	 * @return the current ByteArraySchema instance
+	 */
 	ByteArraySchema format(String format);
 
 	/**
-	   * sets the _default property of this ByteArraySchema to the given _default value.
-	   * 
-	   * @param byte[] _default
-	   * @return ByteArraySchema
-	   */
-	ByteArraySchema _default(byte[] _default);
+	 * Sets the default property of this ByteArraySchema to the given default value.
+	 * 
+	 * @param defaultValue  a value to use as the default
+	 * @return the current ByteArraySchema instance
+	 */
+	ByteArraySchema defaultValue(byte[] defaultValue);
 
 	/**
-	   * sets the _enum property of this ByteArraySchema to the given _enum value.
-	   * 
-	   * @param List&lt;byte[]&gt; _enum
-	   * @return ByteArraySchema
-	   */
-	ByteArraySchema _enum(List<byte[]> _enum);
+	 * Sets the enumerated list of values allowed for objects defined by this schema.
+	 *
+	 * @param enumeration a list of values allowed
+	 * @return the current ByteArraySchema instance
+	 */
+	ByteArraySchema enumeration(List<byte[]> enumeration);
 
 	/**
-	   * Adds the given _enumItem to this ByteArraySchema's List of _enumItems.
-	   *
-	   * @param byte[] _enumItem
-	   */
-	ByteArraySchema addEnumItem(byte[] _enumItem);
+	 * Adds an item of the appropriate type to the enumerated list of values
+	 * allowed.
+	 *
+	 * @param enumerationItem  an object to add to the enumerated values
+	 * @return the current ByteArraySchema instance
+	 */
+	ByteArraySchema addEnumerationItem(byte[] enumerationItem);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ComposedSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ComposedSchema.java
index d00427161..8ca98dcad 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ComposedSchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ComposedSchema.java
@@ -20,104 +20,100 @@
 import java.util.List;
 
 /**
- * ComposedSchema
+ * Create a schema composed of other schemas. An object with this schema can
+ * take a value conforming to one (or more) of the schemas used to build this
+ * one.
  */
 public interface ComposedSchema extends Schema {
 
 	/**
-	   * returns the allOf property from a ComposedSchema instance.
-	   *
-	   * @return List&lt;Schema&gt; allOf
-	   **/
-
+	 * Returns the schemas used by the allOf property in a ComposedSchema instance.
+	 *
+	 * @return the list of schemas used by the allOf property
+	 **/
 	List<Schema> getAllOf();
 
 	/**
-	   * sets the allOf property of this instance of ComposedSchema
-	   * 
-	   * @param List&lt;Schema&gt; allOf
-	   */
+	 * Sets the schemas used by the allOf property of this schema.
+	 * 
+	 * @param allOf  the list of schemas used by the allOf property
+	 */
 	void setAllOf(List<Schema> allOf);
 
 	/**
-	   * sets the allOf property of this instance of ComposedSchema 
-	   * and returns this ComposedSchema
-	   * 
-	   * @param List&lt;Schema&gt; allOf
-	   * @return ComposedSchema
-	   */
+	 * Sets the schemas used by the allOf property of this schema.
+	 * 
+	 * @param allOf  the list of schemas used by the allOf property
+	 * @return the current ComposedSchema instance
+	 */
 	ComposedSchema allOf(List<Schema> allOf);
 
 	/**
-	    * adds the given allOfItem Schema to this ComposedSchema's list of allOfItems
-	    * 
-	    * @param Schema allOfItem
-	    * @return ComposedSchema
-	    */
+	 * Adds the given schema to this ComposedSchema's list of schemas used by the allOf property.
+	 * 
+	 * @param allOfItem  a schema to use with the allOf property
+	 * @return the current ComposedSchema instance
+	 */
 	ComposedSchema addAllOfItem(Schema allOfItem);
 
 	/**
-	   * returns the anyOf property from a ComposedSchema instance.
-	   *
-	   * @return List&lt;Schema&gt; anyOf
-	   **/
-
+	 * Returns the schemas used by the anyOf property in a ComposedSchema instance.
+	 *
+	 * @return the list of schemas used by the anyOf property
+	 **/
 	List<Schema> getAnyOf();
 
 	/**
-	   * sets the anyOf property of this instance of ComposedSchema
-	   * 
-	   * @param List&lt;Schema&gt; anyOf
-	   */
+	 * Sets the schemas used by the anyOf property of this schema.
+	 * 
+	 * @param anyOf  the list of schemas used by the anyOf property
+	 */
 	void setAnyOf(List<Schema> anyOf);
 
 	/**
-	   * sets the anyOf property of this instance of ComposedSchema 
-	   * and returns this ComposedSchema
-	   * 
-	   * @param List&lt;Schema&gt; anyOf
-	   * @return ComposedSchema
-	   */
+	 * Sets the schemas used by the anyOf property of this schema.
+	 * 
+	 * @param anyOf  the list of schemas used by the anyOf property
+	 * @return the current ComposedSchema instance
+	 */
 	ComposedSchema anyOf(List<Schema> anyOf);
 
 	/**
-	    * adds the given anyOfItem Schema to this ComposedSchema's list of anyOfItems
-	    * 
-	    * @param Schema anyOfItem
-	    * @return ComposedSchema
-	    */
+	 * Adds the given schema to this ComposedSchema's list of schemas used by the anyOf property.
+	 * 
+	 * @param anyOfItem  a schema to use with the anyOf property
+	 * @return the current ComposedSchema instance
+	 */
 	ComposedSchema addAnyOfItem(Schema anyOfItem);
 
 	/**
-	   * returns the oneOf property from a ComposedSchema instance.
-	   *
-	   * @return List&lt;Schema&gt; oneOf
-	   **/
-
+	 * Returns the schemas used by the oneOf property in a ComposedSchema instance.
+	 *
+	 * @return the list of schemas used by the oneOf property
+	 **/
 	List<Schema> getOneOf();
 
 	/**
-	   * sets the oneOf property of this instance of ComposedSchema
-	   * 
-	   * @param List&lt;Schema&gt; oneOf
-	   */
+	 * Sets the schemas used by the oneOf property of this schema.
+	 * 
+	 * @param oneOf  the list of schemas used by the oneOf property
+	 */
 	void setOneOf(List<Schema> oneOf);
 
 	/**
-	   * sets the oneOf property of this instance of ComposedSchema 
-	   * and returns this ComposedSchema
-	   * 
-	   * @param List&lt;Schema&gt; oneOf
-	   * @return ComposedSchema
-	   */
+	 * Sets the schemas used by the oneOf property of this schema.
+	 * 
+	 * @param oneOf  the list of schemas used by the oneOf property
+	 * @return the current ComposedSchema instance
+	 */
 	ComposedSchema oneOf(List<Schema> oneOf);
 
 	/**
-	    * adds the given oneOfItem Schema to this ComposedSchema's list of oneOfItems
-	    * 
-	    * @param Schema oneOfItem
-	    * @return ComposedSchema
-	    */
+	 * Adds the given schema to this ComposedSchema's list of schemas used by the oneOf property.
+	 * 
+	 * @param oneOfItem  a schema to use with the oneOf property
+	 * @return the current ComposedSchema instance
+	 */
 	ComposedSchema addOneOfItem(Schema oneOfItem);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/DateSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/DateSchema.java
index 4b4f4f7f5..acea1f34e 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/DateSchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/DateSchema.java
@@ -21,49 +21,53 @@
 import java.util.List;
 
 /**
- * DateSchema
+ * The schema to use for an object that holds date information.
  */
 public interface DateSchema extends Schema<Date> {
 
 	/**
-	   * sets this DateSchema's type property to the given type and
-	   * returns this instance of DateSchema
-	   *
-	   * @param String type
-	   * @return DateSchema
-	   */
+	 * Change this DateSchema's type property from the default value to the
+	 * given string. 
+	 *
+	 * @param type  the name of a valid type
+	 * @return the current DateSchema instance
+	 */
 	DateSchema type(String type);
 
 	/**
-	   * sets this DateSchema's format property to the given format and
-	   * returns this instance of DateSchema
-	   *
-	   * @param String format
-	   * @return DateSchema
-	   */
+	 * Change this DateSchema's format property from the default value to the
+	 * given format. The value may be one of the formats described in the OAS or
+	 * a user defined format.
+	 *
+	 * @param format
+	 *            the string specifying the data format
+	 * @return the current DateSchema instance
+	 */
 	DateSchema format(String format);
 
 	/**
-	   * sets the _default property of this DateSchema to the given _default value.
-	   * 
-	   * @param byte[] _default
-	   * @return DateSchema
-	   */
-	DateSchema _default(Date _default);
+	 * Sets the default property of this DateSchema to the given default value.
+	 * 
+	 * @param defaultValue  a value to use as the default
+	 * @return the current DateSchema instance
+	 */
+	DateSchema defaultValue(Date defaultValue);
 
 	/**
-	   * sets the _enum property of this DateSchema to the given _enum value.
-	   * 
-	   * @param List&lt;byte[]&gt; _enum
-	   * @return DateSchema
-	   */
-	DateSchema _enum(List<Date> _enum);
+	 * Sets the enumerated list of values allowed for objects defined by this schema.
+	 *
+	 * @param enumeration a list of values allowed
+	 * @return the current DateSchema instance
+	 */
+	DateSchema enumeration(List<Date> enumeration);
 
 	/**
-	   * Adds the given _enumItem to this DateSchema's List of _enumItems.
-	   *
-	   * @param byte[] _enumItem
-	   */
-	DateSchema addEnumItem(Date _enumItem);
+	 * Adds an item of the appropriate type to the enumerated list of values
+	 * allowed.
+	 *
+	 * @param enumerationItem  an object to add to the enumerated values
+	 * @return the current DateSchema instance
+	 */
+	DateSchema addEnumerationItem(Date enumerationItem);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/EmailSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/EmailSchema.java
index 13e5b478b..b6567b5c3 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/EmailSchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/EmailSchema.java
@@ -20,49 +20,52 @@
 import java.util.List;
 
 /**
- * EmailSchema
+ * The schema used for an object that holds email data
  */
 public interface EmailSchema extends Schema<String> {
-
 	/**
-	   * sets this EmailSchema's type property to the given type and
-	   * returns this instance of EmailSchema
-	   *
-	   * @param String type
-	   * @return EmailSchema
-	   */
+	 * Change this EmailSchema's type property from the default value to the
+	 * given string. 
+	 *
+	 * @param type  the name of a valid type
+	 * @return the current EmailSchema instance
+	 */
 	EmailSchema type(String type);
 
 	/**
-	   * sets this EmailSchema's format property to the given format and
-	   * returns this instance of EmailSchema
-	   *
-	   * @param String format
-	   * @return EmailSchema
-	   */
+	 * Change this EmailSchema's format property from the default value to the
+	 * given format. The value may be one of the formats described in the OAS or
+	 * a user defined format.
+	 *
+	 * @param format
+	 *            the string specifying the data format
+	 * @return the current EmailSchema instance
+	 */
 	EmailSchema format(String format);
 
 	/**
-	   * sets the _default property of this EmailSchema to the given _default value.
-	   * 
-	   * @param byte[] _default
-	   * @return EmailSchema
-	   */
-	EmailSchema _default(String _default);
+	 * Sets the default property of this EmailSchema to the given default value.
+	 * 
+	 * @param defaultValue  a value to use as the default
+	 * @return the current EmailSchema instance
+	 */
+	EmailSchema defaultValue(String defaultValue);
 
 	/**
-	   * sets the _enum property of this EmailSchema to the given _enum value.
-	   * 
-	   * @param List&lt;byte[]&gt; _enum
-	   * @return EmailSchema
-	   */
-	EmailSchema _enum(List<String> _enum);
+	 * Sets the enumerated list of values allowed for objects defined by this schema.
+	 *
+	 * @param enumeration a list of values allowed
+	 * @return the current EmailSchema instance
+	 */
+	EmailSchema enumeration(List<String> enumeration);
 
 	/**
-	   * Adds the given _enumItem to this EmailSchema's List of _enumItems.
-	   *
-	   * @param byte[] _enumItem
-	   */
-	EmailSchema addEnumItem(String _enumItem);
+	 * Adds an item of the appropriate type to the enumerated list of values
+	 * allowed.
+	 *
+	 * @param enumerationItem  an object to add to the enumerated values
+	 * @return the current EmailSchema instance
+	 */
+	EmailSchema addEnumerationItem(String enumerationItem);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/FileSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/FileSchema.java
index 812a62b7a..e56e0c13d 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/FileSchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/FileSchema.java
@@ -18,28 +18,28 @@
 package org.eclipse.microprofile.openapi.models.media;
 
 /**
- * FileSchema
+ * The schema used for an object that holds file data.
  */
 public interface FileSchema extends Schema<String> {
 
 	/**
-	 * Sets the type property of a FileSchema instance
-	 * to the parameter and returns the instance.
+	 * Change this FileSchema's type property from the default value to the
+	 * given string. 
 	 *
-	 * @param type
-	 * @return FileSchema instance with the set type property.
+	 * @param type  the name of a valid type
+	 * @return the current FileSchema instance
 	 */
-
 	FileSchema type(String type);
 
 	/**
-	 * Sets the format property of a FileSchema instance
-	 * to the parameter and returns the instance.
+	 * Change this FileSchema's format property from the default value to the
+	 * given format. The value may be one of the formats described in the OAS or
+	 * a user defined format.
 	 *
 	 * @param format
-	 * @return FileSchema instance with the set format property.
+	 *            the string specifying the data format
+	 * @return the current FileSchema instance
 	 */
-
 	FileSchema format(String format);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/IntegerSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/IntegerSchema.java
index 82d282217..77a5f555b 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/IntegerSchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/IntegerSchema.java
@@ -20,65 +20,53 @@
 import java.util.List;
 
 /**
- * IntegerSchema
+ * The schema used for an object that holds integer data.
  */
 public interface IntegerSchema extends Schema<Integer> {
 
 	/**
-	 * Sets the type property for an IntegerSchema instance to the
-	 * parameter and returns the instance.
-	 * Type for IntegerSchema instance is "integer"
+	 * Change this IntegerSchema's type property from the default value to the
+	 * given string. 
 	 *
-	 * @param type
-	 * @return IntegerSchema instance with the set type
-	 **/
-
+	 * @param type  the name of a valid type
+	 * @return the current IntegerSchema instance
+	 */
 	IntegerSchema type(String type);
 
 	/**
-	 * Sets the format property for an IntegerSchema instance to the
-	 * parameter and returns the instance.
-	 * The format property for IntegerSchema can be: "int32" or "int64"
+	 * Change this IntegerSchema's format property from the default value to the
+	 * given format. The value may be one of the formats described in the OAS or
+	 * a user defined format.
 	 *
 	 * @param format
-	 * @return IntegerSchema instance with the set format
-	 **/
-
+	 *            the string specifying the data format
+	 * @return the current IntegerSchema instance
+	 */
 	IntegerSchema format(String format);
 
 	/**
-	 * Sets the _default property of an IntegerSchema instance to the
-	 * parameter and returns the instance.
-	 * _default property is inherited from super class Schema
-	 * Method setDefault inherited from Schema super class.
-	 *
-	 * @param _default
-	 * @return IntegerSchema instance with the set _default
-	 * @see SchemaImpl.setDefault
+	 * Sets the default property of this IntegerSchema to the given default value.
+	 * 
+	 * @param defaultValue  a value to use as the default
+	 * @return the current IntegerSchema instance
 	 */
-
-	IntegerSchema _default(Integer _default);
+	IntegerSchema defaultValue(Integer defaultValue);
 
 	/**
-	 * Sets inherited _enum property of an IntegerSchema instance to the
-	 * parameter.
-	 * _enum is inherited from Schema.
+	 * Sets the enumerated list of values allowed for objects defined by this schema.
 	 *
-	 * @param _enum
-	 * @return IntegerSchema instance with the set _enum
-	 * @see SchemaImpl
+	 * @param enumeration a list of values allowed
+	 * @return the current IntegerSchema instance
 	 */
-
-	IntegerSchema _enum(List<Integer> _enum);
+	IntegerSchema enumeration(List<Integer> enumeration);
 
 	/**
-	 * Adds an item to _enum List.
-	 * If _enum is null, will create a new ArrayList and add the item.
+	 * Adds an item of the appropriate type to the enumerated list of values
+	 * allowed.
 	 *
-	 * @param _enumItem
-	 * @return IntegerSchema instance with modified _enum
+	 * @param enumerationItem  an object to add to the enumerated values
+	 * @return the current IntegerSchema instance
 	 */
-
-	IntegerSchema addEnumItem(Integer _enumItem);
+	IntegerSchema addEnumerationItem(Integer enumerationItem);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MapSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MapSchema.java
index d2da1eb65..1b41bac3b 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MapSchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MapSchema.java
@@ -18,18 +18,17 @@
 package org.eclipse.microprofile.openapi.models.media;
 
 /**
- * MapSchema
+ * The schema used for an object that holds map data.
  */
 public interface MapSchema extends Schema {
 
 	/**
-	 * Sets type property of MapSchema instance to the
-	 * parameter and returns the instance.
+	 * Change this MapSchema's type property from the default value to the
+	 * given string. 
 	 *
-	 * @param type
-	 * @return MapSchema instance with the modified type property
+	 * @param type  the name of a valid type
+	 * @return the current MapSchema instance
 	 */
-
 	MapSchema type(String type);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/NumberSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/NumberSchema.java
index c5be14c6f..4e6356e64 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/NumberSchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/NumberSchema.java
@@ -21,53 +21,42 @@
 import java.util.List;
 
 /**
- * NumberSchema
+ * The schema used for an object that holds numeric data.
  */
 public interface NumberSchema extends Schema<BigDecimal> {
 
 	/**
-	 * Sets the type property of a NumberSchema instance
-	 * to the parameter.
+	 * Change this NumberSchema's type property from the default value to the
+	 * given string. 
 	 *
-	 * @param type
-	 * @return NumberSchema instance with the modified type property
+	 * @param type  the name of a valid type
+	 * @return the current NumberSchema instance
 	 */
-
 	NumberSchema type(String type);
 
 	/**
-	 * Sets the _default property of a NumberSchema instance
-	 * to the parameter and returns the instance.
-	 * _default property is inherited from super class Schema
-	 * Method setDefault inherited from Schema super class.
-	 *
-	 * @param _default
-	 * @return The instance of NumberSchema with the modified _default
-	 * @see SchemaImpl.setDefault
+	 * Sets the default property of this NumberSchema to the given default value.
+	 * 
+	 * @param defaultValue  a value to use as the default
+	 * @return the current NumberSchema instance
 	 */
-
-	NumberSchema _default(BigDecimal _default);
+	NumberSchema defaultValue(BigDecimal defaultValue);
 
 	/**
-	 * Sets inherited _enum property of a NumberSchema instance
-	 * to the parameter.
-	 * _enum is inherited from Schema.
+	 * Sets the enumerated list of values allowed for objects defined by this schema.
 	 *
-	 * @param _enum A list of BigDecimal values
-	 * @return A NumberSchema instance with the set _enum
-	 * @see SchemaImpl
+	 * @param enumeration a list of values allowed
+	 * @return the current NumberSchema instance
 	 */
-
-	NumberSchema _enum(List<BigDecimal> _enum);
+	NumberSchema enumeration(List<BigDecimal> enumeration);
 
 	/**
-	 * Adds an item to _enum List.
-	 * If _enum is null, will create a new ArrayList and add the item.
+	 * Adds an item of the appropriate type to the enumerated list of values
+	 * allowed.
 	 *
-	 * @param BigDecimal _enumItem
-	 * @return NumberSchema instance with the modified _enum item
+	 * @param enumerationItem  an object to add to the enumerated values
+	 * @return the current NumberSchema instance
 	 */
-
-	NumberSchema addEnumItem(BigDecimal _enumItem);
+	NumberSchema addEnumerationItem(BigDecimal enumerationItem);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ObjectSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ObjectSchema.java
index d4ced325a..7766c4ae6 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ObjectSchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/ObjectSchema.java
@@ -18,18 +18,17 @@
 package org.eclipse.microprofile.openapi.models.media;
 
 /**
- * ObjectSchema
+ * The schema used for an object containing properties.
  */
 public interface ObjectSchema extends Schema<Object> {
 
 	/**
-	 * Sets the type property of ObjectSchema instance
-	 * to the parameter and returns the instance.
+	 * Change this ObjectSchema's type property from the default value to the
+	 * given string. 
 	 *
-	 * @param type
-	 * @return ObjectSchema instance with modified type property
+	 * @param type  the name of a valid type
+	 * @return the current ObjectSchema instance
 	 */
-
 	ObjectSchema type(String type);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/PasswordSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/PasswordSchema.java
index 2115d31f9..fe14369f3 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/PasswordSchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/PasswordSchema.java
@@ -20,61 +20,53 @@
 import java.util.List;
 
 /**
- * PasswordSchema
+ * The schema used for an object that holds password data.
  */
 public interface PasswordSchema extends Schema<String> {
 
 	/**
-	 * Sets the type property of a PasswordSchema instance
-	 * to the parameter and returns the instance.
+	 * Change this PasswordSchema's type property from the default value to the
+	 * given string. 
 	 *
-	 * @param type
-	 * @return PasswordSchema instance with the modified type property
+	 * @param type  the name of a valid type
+	 * @return the current PasswordSchema instance
 	 */
-
 	PasswordSchema type(String type);
 
 	/**
-	 * Sets the format property for a PasswordSchema instance
-	 * to the parameter and returns the instance.
+	 * Change this PasswordSchema's format property from the default value to the
+	 * given format. The value may be one of the formats described in the OAS or
+	 * a user defined format.
 	 *
 	 * @param format
-	 * @return PasswordSchema instance with modified format
-	 **/
-
+	 *            the string specifying the data format
+	 * @return the current PasswordSchema instance
+	 */
 	PasswordSchema format(String format);
 
 	/**
-	 * Sets the inherited _default property of a PasswordSchema instance
-	 * to the parameter and returns the instance.
-	 * _default is inherited from Schema.
-	 *
-	 * @param _default
-	 * @return The instance of PasswordSchema with the set _default
+	 * Sets the default property of this PasswordSchema to the given default value.
+	 * 
+	 * @param defaultValue  a value to use as the default
+	 * @return the current PasswordSchema instance
 	 */
-
-	PasswordSchema _default(String _default);
+	PasswordSchema defaultValue(String defaultValue);
 
 	/**
-	 * Sets inherited _enum property of a PasswordSchema instance
-	 * to the parameter.
-	 * _enum is inherited from Schema.
+	 * Sets the enumerated list of values allowed for objects defined by this schema.
 	 *
-	 * @param _enum
-	 * @return A PasswordSchema instance with set _enum
-	 * @see SchemaImpl
+	 * @param enumeration a list of values allowed
+	 * @return the current PasswordSchema instance
 	 */
-
-	PasswordSchema _enum(List<String> _enum);
+	PasswordSchema enumeration(List<String> enumeration);
 
 	/**
-	 * Adds an item to _enum List.
-	 * If _enum is null, will create a new ArrayList and add the item.
+	 * Adds an item of the appropriate type to the enumerated list of values
+	 * allowed.
 	 *
-	 * @param _enumItem to be added to the _enum List
-	 * @return PasswordSchema instance with the modified _enum
+	 * @param enumerationItem  an object to add to the enumerated values
+	 * @return the current PasswordSchema instance
 	 */
-
-	PasswordSchema addEnumItem(String _enumItem);
+	PasswordSchema addEnumerationItem(String enumerationItem);
 
 }
\ No newline at end of file
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 ad1c7493e..be72b6ef9 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
@@ -26,709 +26,652 @@
 import org.eclipse.microprofile.openapi.models.ExternalDocumentation;
 
 /**
- * Schema
- *
- * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#schemaObject"
+ * The Schema Object allows the definition of input and output data types. These
+ * types can be objects, but also primitives and arrays. This object is an
+ * extended subset of the
+ * <a href="https://tools.ietf.org/html/draft-wright-json-schema-00">JSON Schema
+ * Specification Wright Draft 00</a>.
+ * <p>
+ * For more information about the properties, see
+ * <a href="http://json-schema.org/">JSON Schema Core</a> and <a href=
+ * "https://tools.ietf.org/html/draft-wright-json-schema-validation-00">JSON
+ * Schema Validation</a>. Unless stated otherwise, the property definitions
+ * follow the JSON Schema.
+ * <p>
+ * Any time a Schema Object can be used, a Reference Object can be used in its
+ * place. This allows referencing an existing definition instead of defining the
+ * same schema again.
+ * 
+ * @see <a href=
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject">OpenAPI
+ *      Specification Schema Object</a>
  */
 public interface Schema<T> extends Constructible, Extensible {
 
 	/**
-	 * returns the name property from a from a Schema instance. Ignored in serialization.
+	 * Returns the discriminator property from this schema instance.
 	 *
-	 * @return String name
+	 * @return the discriminator that is used to differentiate between the
+	 *         schemas which may satisfy the payload description
 	 **/
-	String getName();
-
-	/**
-	 * Sets the name property of a Schema instance
-	 * to the parameter.
-	 *
-	 * @param name
-	 */
-
-	void setName(String name);
-
-	/**
-	 * Sets the name property of a Schema instance
-	 * to the parameter and returns the instance.
-	 *
-	 * @param name
-	 * @return Schema instance with the modified name property
-	 */
-
-	Schema name(String name);
-
-	/**
-	 * returns the discriminator property from a Schema instance.
-	 *
-	 * @return Discriminator discriminator
-	 **/
-
 	Discriminator getDiscriminator();
 
 	/**
-	 * Sets discriminator property of a Schema instance
-	 * to the parameter.
+	 * Sets the discriminator property of this schema instance to the given object.
 	 *
 	 * @param discriminator
+	 *            the object that is used to differentiate between the schemas
+	 *            which may satisfy the payload description
 	 */
-
 	void setDiscriminator(Discriminator discriminator);
 
 	/**
-	 * Sets discriminator property of a Schema instance
-	 * to the parameter and returns the instance.
+	 * Sets the discriminator property of this schema instance to the given object.
 	 *
 	 * @param discriminator
-	 * @return Schema instance with the modified discriminator.
+	 *            the object that is used to differentiate between the schemas
+	 *            which may satisfy the payload description
+	 * @return the current Schema instance
 	 */
-
 	Schema discriminator(Discriminator discriminator);
 
 	/**
-	 * returns the title property from a Schema instance.
+	 * Returns the title property from this schema instance.
 	 *
-	 * @return String title
+	 * @return the title assigned to this schema
 	 **/
-
 	String getTitle();
 
 	/**
-	 * Sets the title property of a Schema instance
-	 * to the parameter.
+	 * Sets the title property of this schema instance
+	 * to the given string.
 	 *
-	 * @param title
+	 * @param title  a title to assign to this schema
 	 */
-
 	void setTitle(String title);
 
 	/**
-	 * Sets the title property of a Schema instance
-	 * to the parameter and returns the modified instance.
+	 * Sets the title property of this schema instance
+	 * to the given string.
 	 *
-	 * @param title
-	 * @return Schema instance with the modified title.
+	 * @param title  a title to assign to this schema
+	 * @return the current Schema instance
 	 */
-
 	Schema title(String title);
 
 	/**
-	 * returns the _default property from a StringSchema instance.
+	 * Returns the default value property from this schema instance.
 	 *
-	 * @return String _default
+	 * @return the default value object
 	 **/
-
-	T getDefault();
+	T getDefaultValue();
 
 	/**
-	 * Set _default property of a Schema instance
-	 * to the parameter.
+	 * Set the default value property of this schema instance
+	 * to the value given.
 	 *
-	 * @param _default
+	 * @param defaultValue a value to use as the default
 	 */
-
-	void setDefault(Object _default);
+	void setDefaultValue(Object defaultValue);
 
 	/**
-	 * Returns _enum property for a Schema instance.
+	 * Set the default value property of this schema instance
+	 * to the value given.
 	 *
-	 * @return List&lt;T&gt; _enum
+	 * @param defaultValue a value to use as the default
+	 * @return the current Schema instance
 	 */
-
-	List<T> getEnum();
+	Schema defaultValue(Object defaultValue);
 
 	/**
-	 * Sets _enum property of a Schema instance
-	 * to the parameter.
+	 * Returns the enumerated list of values allowed for objects defined by this
+	 * schema.
 	 *
-	 * @param _enum
+	 * @return the list of values allowed for objects defined by this schema
 	 */
-
-	void setEnum(List<T> _enum);
+	List<T> getEnumeration();
 
 	/**
-	 * Adds a generic type T item to _enum of a Schema instance.
+	 * Sets the enumerated list of values allowed for objects defined by this schema.
 	 *
-	 * @param _enumItem
+	 * @param enumeration a list of values allowed
 	 */
+	void setEnumeration(List<T> enumeration);
 
-	void addEnumItemObject(T _enumItem);
+	/**
+	 * Adds an item of the appropriate type to the enumerated list of values
+	 * allowed.
+	 *
+	 * @param enumerationItem  an object to add to the enumerated values
+	 */
+	void addEnumerationItemObject(T enumerationItem);
 
 	/**
-	 * returns the multipleOf property from a Schema instance.
+	 * Returns the multipleOf property from this schema instance.
 	 * <p>
 	 * minimum: 0
 	 *
-	 * @return BigDecimal multipleOf
+	 * @return the positive number that restricts the value of the object
 	 **/
-
 	BigDecimal getMultipleOf();
 
 	/**
-	 * Sets multipleOf property of a Schema instance
-	 * to the parameter.
+	 * Sets the multipleOf property of this schema instance to the value given.
 	 *
 	 * @param multipleOf
+	 *            a positive number that restricts the value of objects
+	 *            described by this schema
 	 */
-
 	void setMultipleOf(BigDecimal multipleOf);
 
 	/**
-	 * Sets multipleOf property of a Schema instance
-	 * to the parameter and returns the instance.
+	 * Sets the multipleOf property of this schema instance to the value given.
 	 *
 	 * @param multipleOf
-	 * @return Schema instance with the modified multipleOf property
+	 *            a positive number that restricts the value of objects
+	 *            described by this schema
+	 * @return the current Schema instance
 	 */
-
 	Schema multipleOf(BigDecimal multipleOf);
 
 	/**
-	 * returns the maximum property from a Schema instance.
+	 * Returns the maximum property from this schema instance.
 	 *
-	 * @return BigDecimal maximum
+	 * @return the maximum value of a numeric object
 	 **/
-
 	BigDecimal getMaximum();
 
 	/**
-	 * Sets maximum property of a Schema instance
-	 * to the parameter.
+	 * Sets the maximum property of this schema instance to the value given.
 	 *
-	 * @param maximum
+	 * @param maximum  specifies the maximum numeric value of objects defined by this schema
 	 */
-
 	void setMaximum(BigDecimal maximum);
 
 	/**
-	 * Sets maximum property of a Schema instance to the parameter
-	 * and returns the instance.
+	 * Sets the maximum property of this schema instance to the value given.
 	 *
-	 * @param maximum
-	 * @return Schema instance with the modified maximum property
+	 * @param maximum  specifies the maximum numeric value of objects defined by this schema
+	 * @return the current Schema instance
 	 */
-
 	Schema maximum(BigDecimal maximum);
 
 	/**
-	 * returns the exclusiveMaximum property from a Schema instance.
+	 * Returns the exclusiveMaximum property from this schema instance.
 	 *
-	 * @return Boolean exclusiveMaximum
+	 * @return whether the numeric value of objects must be less than the maximum property
 	 **/
-
 	Boolean getExclusiveMaximum();
 
 	/**
-	 * Sets exclusiveMaximum property of a Schema instance
-	 * to the parameter.
+	 * Sets the exclusiveMaximum property of this schema instance to the value
+	 * given.
 	 *
 	 * @param exclusiveMaximum
+	 *            when true the numeric value of objects defined by this schema
+	 *            must be less than indicated by the maximum property
 	 */
-
 	void setExclusiveMaximum(Boolean exclusiveMaximum);
 
 	/**
-	 * Sets exclusiveMaximum property of a Schema instance to the parameter
-	 * and returns the instance.
+	 * Sets the exclusiveMaximum property of this schema instance to the value
+	 * given.
 	 *
 	 * @param exclusiveMaximum
-	 * @return Schema instance with modified exclusiveMaximum property.
+	 *            when true the numeric value of objects defined by this schema
+	 *            must be less than indicated by the maximum property
+	 * @return the current Schema instance
 	 */
-
 	Schema exclusiveMaximum(Boolean exclusiveMaximum);
 
 	/**
-	 * returns the minimum property from a Schema instance.
+	 * Returns the minimum property from this schema instance.
 	 *
-	 * @return BigDecimal minimum
+	 * @return the minimum value of a numeric object
 	 **/
-
 	BigDecimal getMinimum();
 
 	/**
-	 * Sets minimum property of a Schema instance
-	 * to the parameter.
+	 * Sets the minimum property of this schema instance to the value given.
 	 *
-	 * @param minimum
+	 * @param minimum  specifies the minimum numeric value of objects defined by this schema
 	 */
-
 	void setMinimum(BigDecimal minimum);
 
 	/**
-	 * Sets minimum property of a Schema instance
-	 * to the parameter and returns the instance
+	 * Sets the minimum property of this schema instance to the value given.
 	 *
-	 * @param minimum
-	 * @return Schema instance with the modified minimum property.
+	 * @param minimum  specifies the minimum numeric value of objects defined by this schema
+	 * @return the current Schema instance
 	 */
-
 	Schema minimum(BigDecimal minimum);
 
 	/**
-	 * returns the exclusiveMinimum property from a Schema instance.
+	 * Returns the exclusiveMinimum property from this schema instance.
 	 *
-	 * @return Boolean exclusiveMinimum
+	 * @return whether the numeric value of objects must be greater than the minimum property
 	 **/
-
 	Boolean getExclusiveMinimum();
 
 	/**
-	 * Sets exclusiveMinimum property of a Schema instance
-	 * to the parameter.
+	 * Sets the exclusiveMinimum property of this schema instance to the value
+	 * given.
 	 *
 	 * @param exclusiveMinimum
+	 *            when true the numeric value of objects defined by this schema
+	 *            must be greater than indicated by the minimum property
 	 */
-
 	void setExclusiveMinimum(Boolean exclusiveMinimum);
 
 	/**
-	 * Sets exclusiveMinimum property of a Schema instance
-	 * to the parameter and returns the instance.
+	 * Sets the exclusiveMinimum property of this schema instance to the value
+	 * given.
 	 *
 	 * @param exclusiveMinimum
-	 * @return Schema instance with the modified exclusiveMinimum property.
+	 *            when true the numeric value of objects defined by this schema
+	 *            must be greater than indicated by the minimum property
+	 * @return the current Schema instance
 	 */
-
 	Schema exclusiveMinimum(Boolean exclusiveMinimum);
 
 	/**
-	 * returns the maxLength property from a Schema instance.
+	 * Returns the maxLength property from this schema instance.
 	 * <p>
 	 * minimum: 0
 	 *
-	 * @return Integer maxLength
+	 * @return the maximum length of objects e.g. strings
 	 **/
-
 	Integer getMaxLength();
 
 	/**
-	 * Sets maxLength property of a Schema instance
-	 * to the parameter.
+	 * Sets the maxLength property of this schema instance to the value given.
 	 *
-	 * @param maxLength
+	 * @param maxLength  the maximum length of objects defined by this schema
 	 */
-
 	void setMaxLength(Integer maxLength);
 
 	/**
-	 * Sets maxLength property of a Schema instance
-	 * to the parameter and returns the instance
+	 * Sets the maxLength property of this schema instance to the value given.
 	 *
-	 * @param maxLength
-	 * @return Schema instance with the modified maxLength property.
+	 * @param maxLength  the maximum length of objects defined by this schema
+	 * @return the current Schema instance
 	 */
-
 	Schema maxLength(Integer maxLength);
 
 	/**
-	 * returns the minLength property from a Schema instance.
+	 * Returns the minLength property from this schema instance.
 	 * <p>
 	 * minimum: 0
 	 *
-	 * @return Integer minLength
+	 * @return the minimum length of objects e.g. strings
 	 **/
-
 	Integer getMinLength();
 
 	/**
-	 * Sets minLength property of a Schema instance
-	 * to the parameter.
+	 * Sets the minLength property of this schema instance to the value given.
 	 *
-	 * @param minLength
+	 * @param minLength  the minimum length of objects defined by this schema
 	 */
-
 	void setMinLength(Integer minLength);
 
 	/**
-	 * Sets minLength property of a Schema instance
-	 * to the parameter and returns the instance
+	 * Sets the minLength property of this schema instance to the value given.
 	 *
-	 * @param minLength
-	 * @return Schema instance with the modified minLength property.
+	 * @param minLength  the minimum length of objects defined by this schema
+	 * @return the current Schema instance
 	 */
-
 	Schema minLength(Integer minLength);
 
 	/**
-	 * returns the pattern property from a Schema instance.
+	 * Returns the pattern property from this schema instance.
 	 *
-	 * @return String pattern
+	 * @return the regular expression which restricts the value of an object e.g. a string
 	 **/
-
 	String getPattern();
 
 	/**
-	 * Sets pattern property of a Schema instance
-	 * to the parameter.
+	 * Sets the pattern property of this schema instance to the string given.
 	 *
-	 * @param pattern
+	 * @param pattern  the regular expression which restricts objects defined by this schema
 	 */
-
 	void setPattern(String pattern);
 
 	/**
-	 * Sets pattern property of a Schema instance
-	 * to the parameter and returns the instance
+	 * Sets the pattern property of this schema instance to the string given.
 	 *
-	 * @param pattern
-	 * @return Schema instance with the modified pattern property.
+	 * @param pattern  the regular expression which restricts objects defined by this schema
+	 * @return the current Schema instance
 	 */
-
 	Schema pattern(String pattern);
 
 	/**
-	 * returns the maxItems property from a Schema instance.
+	 * Returns the maxItems property from this schema instance.
 	 * <p>
 	 * minimum: 0
 	 *
-	 * @return Integer maxItems
+	 * @return the maximum number of elements in the object e.g. array elements
 	 **/
-
 	Integer getMaxItems();
 
 	/**
-	 * Sets maxItems property of a Schema instance
-	 * to the parameter.
+	 * Sets the maxItems property of this schema instance to the value given.
 	 *
 	 * @param maxItems
+	 *            the maximum number of elements in objects defined by this
+	 *            schema e.g. array elements
 	 */
-
 	void setMaxItems(Integer maxItems);
 
 	/**
-	 * Sets maxItems property of a Schema instance
-	 * to the parameter and returns the instance.
+	 * Sets the maxItems property of this schema instance to the value given.
 	 *
 	 * @param maxItems
-	 * @return Schema instance with the modified maxItems property.
+	 *            the maximum number of elements in objects defined by this
+	 *            schema e.g. array elements
+	 * @return the current Schema instance
 	 */
-
 	Schema maxItems(Integer maxItems);
 
 	/**
-	 * returns the minItems property from a Schema instance.
+	 * Returns the minItems property from this schema instance.
 	 * <p>
 	 * minimum: 0
 	 *
-	 * @return Integer minItems
+	 * @return the minimum number of elements in the object e.g. array elements
 	 **/
-
 	Integer getMinItems();
 
 	/**
-	 * Sets minItems property of Schema instance
-	 * to the parameter.
+	 * Sets the minItems property of this schema instance to the value given.
 	 *
 	 * @param minItems
+	 *            the minimum number of elements in objects defined by this
+	 *            schema e.g. array elements
 	 */
-
 	void setMinItems(Integer minItems);
 
 	/**
-	 * Sets minItems property of a Schema instance
-	 * to the parameter and returns the instance.
+	 * Sets the minItems property of this schema instance to the value given.
 	 *
 	 * @param minItems
-	 * @return Schema instance with the modified minItems property.
+	 *            the minimum number of elements in objects defined by this
+	 *            schema e.g. array elements
+	 * @return the current Schema instance
 	 */
-
 	Schema minItems(Integer minItems);
 
 	/**
-	 * returns the uniqueItems property from a Schema instance.
+	 * Returns the uniqueItems property from this schema instance.
 	 *
-	 * @return Boolean uniqueItems
+	 * @return whether to ensure items are unique
 	 **/
-
 	Boolean getUniqueItems();
 
 	/**
-	 * Sets uniqueItems property of a Schema instance
-	 * to the parameter.
+	 * Sets the uniqueItems property of this schema instance to the value given.
 	 *
 	 * @param uniqueItems
+	 *            ensure the items (e.g. array elements) are unique in objects
+	 *            defined by this schema
 	 */
-
 	void setUniqueItems(Boolean uniqueItems);
 
 	/**
-	 * Sets uniqueItems property of a Schema instance
-	 * to the parameter and returns the instance.
+	 * Sets the uniqueItems property of this schema instance to the value given.
 	 *
 	 * @param uniqueItems
-	 * @return Schema instance with the modified uniqueItems property.
+	 *            ensure the items (e.g. array elements) are unique in objects
+	 *            defined by this schema
+	 * @return the current Schema instance
 	 */
-
 	Schema uniqueItems(Boolean uniqueItems);
 
 	/**
-	 * returns the maxProperties property from a Schema instance.
+	 * Returns the maxProperties property from this schema instance.
 	 * <p>
 	 * minimum: 0
 	 *
-	 * @return Integer maxProperties
+	 * @return the maximum number of properties allowed in the object
 	 **/
-
 	Integer getMaxProperties();
 
 	/**
-	 * Sets maxProperties property of a Schema instance
-	 * to the parameter.
+	 * Sets the maxProperties property of this schema instance to the value given.
 	 *
-	 * @param maxProperties
+	 * @param maxProperties  limit the number of properties in objects
+	 *            defined by this schema
 	 */
-
 	void setMaxProperties(Integer maxProperties);
 
 	/**
-	 * Sets maxProperties property of a Schema instance
-	 * to the parameter and returns the instance.
+	 * Sets the maxProperties property of this schema instance to the value given.
 	 *
-	 * @param maxProperties
-	 * @return Schema instance with the modified maxProperty property.
+	 * @param maxProperties  limit the number of properties in objects
+	 *            defined by this schema
+	 * @return the current Schema instance
 	 */
-
 	Schema maxProperties(Integer maxProperties);
 
 	/**
-	 * returns the minProperties property from a Schema instance.
+	 * Returns the minProperties property from this schema instance.
 	 * <p>
 	 * minimum: 0
 	 *
-	 * @return Integer minProperties
+	 * @return the minimum number of properties allowed in the object
 	 **/
-
 	Integer getMinProperties();
 
 	/**
-	 * Sets minProperties property of a Schema instance
-	 * to the parameter.
+	 * Sets the minProperties property of this schema instance to the value given.
 	 *
-	 * @param minProperties
+	 * @param minProperties  limit the number of properties in objects
+	 *            defined by this schema
 	 */
-
 	void setMinProperties(Integer minProperties);
 
 	/**
-	 * Sets minProperties property of a Schema instance
-	 * to the parameter and returns the instance.
+	 * Sets the minProperties property of this schema instance to the value given.
 	 *
-	 * @param minProperties
-	 * @return Schema instance with the modified minProperty property.
+	 * @param minProperties  limit the number of properties in objects
+	 *            defined by this schema
+	 * @return the current Schema instance
 	 */
-
 	Schema minProperties(Integer minProperties);
 
 	/**
-	 * returns the required property from a Schema instance.
+	 * Returns the required property from this schema instance.
 	 *
-	 * @return List&lt;String&gt; required
+	 * @return the list of fields required in objects defined by this schema
 	 **/
-
 	List<String> getRequired();
 
 	/**
-	 * Sets required property of a Schema instance if
-	 * it is null or does not contain the List items
-	 * passed in as method arguments.
+	 * Sets the list of fields required in objects defined by this schema.
 	 *
-	 * @param required
+	 * @param required  the list of fields required in objects defined by this schema
 	 */
-
 	void setRequired(List<String> required);
 
 	/**
-	 * Sets required List property of a Schema instance
-	 * to the parameter and returns the instance.
+	 * Sets the list of fields required in objects defined by this schema.
 	 *
-	 * @param required
-	 * @return Schema instance with the set required property.
+	 * @param required  the list of fields required in objects defined by this schema
+	 * @return the current Schema instance
 	 */
-
 	Schema required(List<String> required);
 
 	/**
-	 * Adds an item to required List of a Schema instance.
-	 * Creates new ArrayList if instance's required property is null.
+	 * Adds the name of an item to the list of fields required in objects
+	 * defined by this schema.
 	 *
 	 * @param requiredItem
-	 * @return Schema instance with added required item.
+	 *            the name of an item required in objects defined by this schema
+	 *            instance
+	 * @return the current Schema instance
 	 */
-
 	Schema addRequiredItem(String requiredItem);
 
 	/**
-	 * returns the type property from a Schema instance.
+	 * Returns the type property from this schema.
 	 *
-	 * @return String type
+	 * @return the name of the type used in this schema
 	 **/
-
 	String getType();
 
 	/**
-	 * Sets the type property of a Schema instance
-	 * to the parameter.
+	 * Sets the type used by this schema to the string given.
 	 *
-	 * @param type
+	 * @param type  the name of the type used by this schema
 	 */
-
 	void setType(String type);
 
 	/**
-	 * Sets the type property of a Schema instance
-	 * to the parameter and returns the instance.
+	 * Sets the type used by this schema to the string given.
 	 *
-	 * @param type
-	 * @return Schema instance with the modified type property.
+	 * @param type  the name of the type used by this schema
+	 * @return the current Schema instance
 	 */
-
 	Schema type(String type);
 
 	/**
-	 * returns the not property from a Schema instance.
+	 * Returns a schema which describes properties not allowed in objects defined by the current schema. 
 	 *
-	 * @return Schema not
+	 * @return the not property's schema
 	 **/
-
 	Schema getNot();
 
 	/**
-	 * Sets the not property of a Schema instance
-	 * to the parameter.
+	 * Sets the not property to a schema which describes properties not allowed
+	 * in objects defined by the current schema.
 	 *
-	 * @param not
+	 * @param not  the schema which describes properties not allowed
 	 */
-
 	void setNot(Schema not);
 
 	/**
-	 * Sets the not property of a Schema instance
-	 * to the parameter and
-	 * returns the instance.
+	 * Sets the not property to a schema which describes properties not allowed
+	 * in objects defined by the current schema.
 	 *
-	 * @param not
-	 * @return Schema with the modified not property.
+	 * @param not  the schema which describes properties not allowed
+	 * @return the current Schema instance
 	 */
-
 	Schema not(Schema not);
 
 	/**
-	 * returns the properties property from a Schema instance.
+	 * Returns the properties defined in this schema.
 	 *
-	 * @return Map&lt;String, Schema&gt; properties
+	 * @return a map which associates property names with the schemas that
+	 *         describe their contents
 	 **/
-
 	Map<String, Schema> getProperties();
 
 	/**
-	 * Sets properties property of a Schema instance
-	 * to the parameter.
+	 * Sets the properties of this schema instance to the map provided.
 	 *
 	 * @param properties
+	 *            a map which associates property names with the schemas that
+	 *            describe their contents
 	 */
-
 	void setProperties(Map<String, Schema> properties);
 
 	/**
-	 * Sets properties property of a Schema instance
-	 * to the parameter and returns the modified instance.
+	 * Sets the properties of this schema instance to the map provided.
 	 *
 	 * @param properties
-	 * @return Schema instance with the set properties property.
+	 *            a map which associates property names with the schemas that
+	 *            describe their contents
+	 * @return the current Schema instance
 	 */
-
 	Schema properties(Map<String, Schema> properties);
 
 	/**
-	 * Adds a Schema property item at specified key to properties
-	 * property of a Schema instance and returns the instance.
+	 * Adds a schema property of the provided name using the given schema.
 	 *
 	 * @param key
+	 *            the name of a new schema property
 	 * @param propertiesItem
-	 * @return Schema instance with added property item.
+	 *            the schema which describes the properties of the named
+	 *            property
+	 * @return the current Schema instance
 	 */
-
 	Schema addProperties(String key, Schema propertiesItem);
 
 	/**
-	 * returns the additionalProperties property from a Schema instance.
+	 * Returns the schema which defines new properties added to objects defined
+	 * by the current schema.
 	 *
-	 * @return Schema additionalProperties
+	 * @return this schema's additionalProperties property
 	 **/
-
 	Schema getAdditionalProperties();
 
 	/**
-	 * Sets additionalProperties property of a Schema instance
-	 * to the parameter.
+	 * Sets the schema which defines new properties added to objects defined by
+	 * the current schema.
 	 *
 	 * @param additionalProperties
+	 *            a schema which defines additional properties
 	 */
-
 	void setAdditionalProperties(Schema additionalProperties);
 
 	/**
-	 * Sets additionalProperties property of a Schema instance
-	 * to the parameter and returns the instance.
+	 * Sets the schema which defines new properties added to objects defined by
+	 * the current schema.
 	 *
 	 * @param additionalProperties
-	 * @return Schema instance with the set additionalProperties property
+	 *            a schema which defines additional properties
+	 * @return the current Schema instance
 	 */
-
 	Schema additionalProperties(Schema additionalProperties);
 
 	/**
-	 * returns the description property from a Schema instance.
+	 * Returns a description of the purpose of this schema.
 	 *
-	 * @return String description
+	 * @return a string containing a description
 	 **/
-
 	String getDescription();
 
 	/**
-	 * Sets description property of a Schema instance
-	 * to the parameter.
+	 * Sets the description property of this schema 
+	 * to the given string.
 	 *
-	 * @param description
+	 * @param description  a string containing a description of the purpose of this schema
 	 */
-
 	void setDescription(String description);
 
 	/**
-	 * Sets description property of a Schema instance
-	 * to the parameter and returns the instance.
+	 * Sets the description property of this schema 
+	 * to the given string.
 	 *
-	 * @param description
-	 * @return Schema instance with the set description property
+	 * @param description  a string containing a description of the purpose of this schema
+	 * @return the current Schema instance
 	 */
-
 	Schema description(String description);
 
 	/**
-	 * returns the format property from a Schema instance.
+	 * Returns the format property from this schema instance. This property clarifies the 
+	 * data type specified in the type property. 
 	 *
-	 * @return String format
+	 * @return a string describing the format of the data in this schema
 	 **/
-
 	String getFormat();
 
 	/**
-	 * Sets format property of a Schema instance
-	 * to the parameter.
+	 * Sets the format property of this schema instance to the given string. The value may
+	 * be one of the formats described in the OAS or a user defined format.
 	 *
 	 * @param format
+	 *            the string specifying the data format
 	 */
-
 	void setFormat(String format);
 
 	/**
-	 * Sets format property of a Schema instance
-	 * to the parameter and returns the instance.
+	 * Sets the format property of this schema instance to the given string. The value may
+	 * be one of the formats described in the OAS or a user defined format.
 	 *
 	 * @param format
-	 * @return Schema instance with the set format property.
+	 *            the string specifying the data format
+	 * @return the current Schema instance
 	 */
-
 	Schema format(String format);
 
 	/**
@@ -758,195 +701,172 @@ public interface Schema<T> extends Constructible, Extensible {
 	Schema $ref(String $ref);
 
 	/**
-	 * returns the nullable property from a Schema instance.
+	 * Returns the nullable property from this schema instance which indicates whether null is a 
+	 * valid value.
 	 *
-	 * @return Boolean nullable
+	 * @return the nullable property
 	 **/
-
 	Boolean getNullable();
 
 	/**
-	 * Sets nullable property of a Schema instance
-	 * to the parameter.
+	 * Sets the nullable property of this schema instance. Specify true if this 
+	 * schema will allow null values. 
 	 *
-	 * @param nullable
+	 * @param nullable  a boolean value indicating this schema allows a null value.
 	 */
-
 	void setNullable(Boolean nullable);
 
 	/**
-	 * Sets nullable property of a Schema instance
-	 * to the parameter and return the instance.
+	 * Sets the nullable property of this schema instance. Specify true if this 
+	 * schema will allow null values. 
 	 *
-	 * @param nullable
-	 * @return Schema instance with the set nullable property.
+	 * @param nullable  a boolean value indicating this schema allows a null value.
+	 * @return the current Schema instance
 	 */
-
 	Schema nullable(Boolean nullable);
 
 	/**
-	 * returns the readOnly property from a Schema instance.
+	 * Returns the readOnly property from this schema instance.
 	 *
-	 * @return Boolean readOnly
+	 * @return indication that the schema is only valid in a response message
 	 **/
-
 	Boolean getReadOnly();
 
 	/**
-	 * Sets readOnly property of a Schema instance
-	 * to the parameter.
+	 * Sets the readOnly property of this schema. Only valid when the schema is
+	 * the property in an object.
 	 *
-	 * @param readOnly
+	 * @param readOnly  true indicates the schema should not be sent as part of a request message
 	 */
-
 	void setReadOnly(Boolean readOnly);
 
 	/**
-	 * Sets readOnly property of a Schema instance
-	 * to the parameter and return the instance.
+	 * Sets the readOnly property of this schema. Only valid when the schema is
+	 * the property in an object.
 	 *
-	 * @param readOnly
-	 * @return Schema instance with the set readOnly property.
+	 * @param readOnly  true indicates the schema should not be sent as part of a request message
+	 * @return the current Schema instance
 	 */
-
 	Schema readOnly(Boolean readOnly);
 
 	/**
-	 * returns the writeOnly property from a Schema instance.
+	 * Returns the writeOnly property from this schema instance.
 	 *
-	 * @return Boolean writeOnly
+	 * @return indication that the schema is only valid in a request message
 	 **/
-
 	Boolean getWriteOnly();
 
 	/**
-	 * Sets writeOnly property of a Schema instance
-	 * to the parameter.
+	 * Sets the writeOnly property of this schema. Only valid when the schema is
+	 * the property in an object.
 	 *
-	 * @param writeOnly
+	 * @param writeOnly  true indicates the schema should not be sent as part of a response message
 	 */
-
 	void setWriteOnly(Boolean writeOnly);
 
 	/**
-	 * Sets writeOnly property of a Schema instance
-	 * to the parameter and return the instance.
+	 * Sets the writeOnly property of this schema. Only valid when the schema is
+	 * the property in an object.
 	 *
-	 * @param writeOnly
-	 * @return Schema instance with the set writeOnly property.
+	 * @param writeOnly  true indicates the schema should not be sent as part of a response message
+	 * @return the current Schema instance
 	 */
-
 	Schema writeOnly(Boolean writeOnly);
 
 	/**
-	 * returns the example property from a Schema instance.
+	 * Returns the example property from this schema instance.
 	 *
-	 * @return String example
+	 * @return an object which is an example of an instance of this schema
 	 **/
-
 	Object getExample();
 
 	/**
-	 * Sets example property of a Schema instance
-	 * to the parameter.
+	 * Sets the example property of this schema instance. To represent examples
+	 * that cannot be naturally represented in JSON or YAML, a string value can
+	 * be used to contain the example with escaping where necessary.
 	 *
-	 * @param example
+	 * @param example  an object which is an instance of this schema
 	 */
-
 	void setExample(Object example);
 
 	/**
-	 * Sets example property of a Schema instance
-	 * to the parameter and return the instance.
+	 * Sets the example property of this schema instance. To represent examples
+	 * that cannot be naturally represented in JSON or YAML, a string value can
+	 * be used to contain the example with escaping where necessary.
 	 *
-	 * @param example
-	 * @return Schema instance with the set example property.
+	 * @param example  an object which is an instance of this schema
+	 * @return the current Schema instance
 	 */
-
 	Schema example(Object example);
 
 	/**
-	 * returns the externalDocs property from a Schema instance.
+	 * Returns the externalDocs property from this schema instance.
 	 *
-	 * @return ExternalDocumentation externalDocs
+	 * @return additional external documentation for this schema
 	 **/
-
 	ExternalDocumentation getExternalDocs();
 
 	/**
-	 * Sets externalDocs property of a Schema instance
-	 * to the parameter.
+	 * Sets the externalDocs property of this schema to the indicated value.
 	 *
-	 * @param externalDocs
+	 * @param externalDocs  an additional external documentation object
 	 */
-
 	void setExternalDocs(ExternalDocumentation externalDocs);
 
 	/**
-	 * Sets externalDocs property of a Schema instance
-	 * to the parameter and
-	 * return the instance.
+	 * Sets the externalDocs property of this schema to the indicated value.
 	 *
-	 * @param externalDocs
-	 * @return Schema instance with the set externalDocs property
+	 * @param externalDocs  an additional external documentation object
+	 * @return the current Schema instance
 	 */
-
 	Schema externalDocs(ExternalDocumentation externalDocs);
 
 	/**
-	 * returns the deprecated property from a Schema instance.
+	 * Returns the deprecated property from this schema instance.
 	 *
-	 * @return Boolean deprecated
+	 * @return indication that the schema is deprecated and should be transitioned out of usage
 	 **/
-
 	Boolean getDeprecated();
 
 	/**
-	 * Sets deprecated property of a Schema instance
-	 * to the parameter.
+	 * Sets the deprecated property of this schema. This 
+	 * specifies that the schema is deprecated and should be transitioned out of usage
 	 *
-	 * @param deprecated
+	 * @param deprecated  true to indicate this schema is deprecated
 	 */
-
 	void setDeprecated(Boolean deprecated);
 
 	/**
-	 * Sets deprecated property of a Schema instance
-	 * to the parameter and
-	 * return the instance.
+	 * Sets the deprecated property of this schema. This 
+	 * specifies that the schema is deprecated and should be transitioned out of usage
 	 *
-	 * @param deprecated
-	 * @return Schema instance with the set deprecated property
+	 * @param deprecated  true to indicate this schema is deprecated
+	 * @return the current Schema instance
 	 */
-
 	Schema deprecated(Boolean deprecated);
 
 	/**
-	 * returns the xml property from a Schema instance.
+	 * Returns the xml property from this schema instance.
 	 *
-	 * @return XML xml
+	 * @return a metadata object that allows for more fine-tuned XML model definitions
 	 **/
-
 	XML getXml();
-
+	
 	/**
-	 * Sets xml property of a Schema instance
-	 * to the parameter.
+	 * Sets the xml property of this schema instance. It may only be set on properties schemas
+	 * and adds additional metadata to describe the XML representation of this property.
 	 *
-	 * @param xml
+	 * @param xml  a metadata object to describe the XML representation of this property
 	 */
-
 	void setXml(XML xml);
 
 	/**
-	 * Sets xml property of a Schema instance
-	 * to the parameter and
-	 * return the instance.
+	 * Sets the xml property of this schema instance. It may only be set on properties schemas
+	 * and adds additional metadata to describe the XML representation of this property.
 	 *
-	 * @param xml
-	 * @return Schema instance with the set xml property
+	 * @param xml  a metadata object to describe the XML representation of this property
+	 * @return the current Schema instance
 	 */
-
 	Schema xml(XML xml);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/StringSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/StringSchema.java
index 542411684..66177f1c1 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/StringSchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/StringSchema.java
@@ -20,57 +20,42 @@
 import java.util.List;
 
 /**
- * StringSchema
+ * The schema used for an object that holds a string.
  */
 public interface StringSchema extends Schema<String> {
 
 	/**
-	 * Sets the type property of a StringSchema instance
-	 * to the parameter and returns the instance.
+	 * Change this StringSchema's type property from the default value to the
+	 * given string. 
 	 *
-	 * @param type
-	 * @return StringSchema instance with modified type property.
+	 * @param type  the name of a valid type
+	 * @return the current StringSchema instance
 	 */
-
 	StringSchema type(String type);
 
 	/**
-	 * Sets inherited _default property of a StringSchema instance
-	 * to the parameter and returns the instance.
-	 * _default is inherited from super class Schema
-	 *
-	 * @param _default
-	 * @return StringSchema instance with the modified _default property
-	 * @see SchemaImpl
+	 * Sets the default property of this StringSchema to the given default value.
+	 * 
+	 * @param defaultValue  a value to use as the default
+	 * @return the current StringSchema instance
 	 */
-
-	StringSchema _default(String _default);
+	StringSchema defaultValue(String defaultValue);
 
 	/**
-	 * Sets inherited _enum property of a StringSchema instance
-	 * to the parameter.
-	 * <p>
-	 * _enum is inherited from super class Schema.
-	 * <p>
-	 * Uses super class method setEnum() and returns
-	 * the instance.
+	 * Sets the enumerated list of values allowed for objects defined by this schema.
 	 *
-	 * @param _enum
-	 * @return StringSchema instance with modified _enum.
-	 * @see SchemaImpl
+	 * @param enumeration a list of values allowed
+	 * @return the current StringSchema instance
 	 */
-
-	StringSchema _enum(List<String> _enum);
+	StringSchema enumeration(List<String> enumeration);
 
 	/**
-	 * Adds an item to _enum of a StringSchema instance
-	 * and returns the instance.
-	 * If _enum is null, creates a new ArrayList and adds item.
+	 * Adds an item of the appropriate type to the enumerated list of values
+	 * allowed.
 	 *
-	 * @param _enumItem
-	 * @return StringSchema instance with the added _enum item.
+	 * @param enumerationItem  an object to add to the enumerated values
+	 * @return the current StringSchema instance
 	 */
-
-	StringSchema addEnumItem(String _enumItem);
+	StringSchema addEnumerationItem(String enumerationItem);
 
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/UUIDSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/UUIDSchema.java
index ec66699a3..32eb52747 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/UUIDSchema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/UUIDSchema.java
@@ -21,81 +21,62 @@
 import java.util.UUID;
 
 /**
- * UUIDSchema
+ * The schema used for an object that holds a UUID.
  */
 public interface UUIDSchema extends Schema<UUID> {
 
 	/**
-	 * Sets the type property of a UUIDSchema instance
-	 * to the parameter and returns the instance.
+	 * Change this UUIDSchema's type property from the default value to the
+	 * given string. 
 	 *
-	 * @param type
-	 * @return UUIDSchema instance with modified type property.
+	 * @param type  the name of a valid type
+	 * @return the current UUIDSchema instance
 	 */
-
 	UUIDSchema type(String type);
 
 	/**
-	 * Sets format property of a UUIDSchema instance
-	 * to the parameter and returns the instance.
+	 * Change this UUIDSchema's format property from the default value to the
+	 * given format. The value may be one of the formats described in the OAS or
+	 * a user defined format.
 	 *
 	 * @param format
-	 * @return UUIDSchema instance with the modified format
+	 *            the string specifying the data format
+	 * @return the current UUIDSchema instance
 	 */
-
 	UUIDSchema format(String format);
 
 	/**
-	 * Sets inherited _default property of a UUIDSchema instance
-	 * to the parameter and returns the instance.
-	 * _default is inherited from super class Schema
-	 *
-	 * <p>
-	 * Sets _default from UUID argument
-	 *
-	 * @param _default
-	 * @return UUIDSchema instance with the modified _default property
-	 * @see SchemaImpl
+	 * Sets the default property of this UUIDSchema to the given default value.
+	 * 
+	 * @param defaultValue  a value to use as the default
+	 * @return the current UUIDSchema instance
 	 */
-
-	UUIDSchema _default(UUID _default);
+	UUIDSchema defaultValue(UUID defaultValue);
 
 	/**
-	 * Sets inherited _default property of a UUIDSchema instance
-	 * to the parameter and returns the instance.
-	 * _default is inherited from super class Schema
-	 *
-	 * <p>
-	 * Sets _default from String argument
-	 *
-	 * @param _default
-	 * @return UUIDSchema instance with the modified _default property
-	 * @see SchemaImpl
+	 * Sets the default property of this UUIDSchema by converting the given string
+	 * to a valid default value.
+	 * 
+	 * @param defaultValue  a value to use as the default
+	 * @return the current UUIDSchema instance
 	 */
-
-	UUIDSchema _default(String _default);
+	UUIDSchema defaultValue(String defaultValue);
 
 	/**
-	 * Sets inherited _enum property of a UUIDSchema instance
-	 * to the parameter.
-	 * _enum is inherited from super class Schema.
+	 * Sets the enumerated list of values allowed for objects defined by this schema.
 	 *
-	 * @param _enum
-	 * @return UUIDSchema instance with modified _enum.
-	 * @see SchemaImpl
+	 * @param enumeration a list of values allowed
+	 * @return the current UUIDSchema instance
 	 */
-
-	UUIDSchema _enum(List<UUID> _enum);
+	UUIDSchema enumeration(List<UUID> enumeration);
 
 	/**
-	 * Adds an item to _enum of a UUIDSchema instance
-	 * to the parameter and returns the instance.
-	 * If _enum is null, creates a new ArrayList and adds item.
+	 * Adds an item of the appropriate type to the enumerated list of values
+	 * allowed.
 	 *
-	 * @param _enumItem
-	 * @return UUIDSchema instance with the added _enum item.
+	 * @param enumerationItem  an object to add to the enumerated values
+	 * @return the current UUIDSchema instance
 	 */
-
-	UUIDSchema addEnumItem(UUID _enumItem);
+	UUIDSchema addEnumerationItem(UUID enumerationItem);
 
 }
\ No newline at end of file

From 198772e3dd2ab730e18f97e1e4bcc9195df403b5 Mon Sep 17 00:00:00 2001
From: Michael Glavassevich <mrglavas@ca.ibm.com>
Date: Tue, 31 Oct 2017 15:58:19 -0400
Subject: [PATCH 23/23] Factor out base interface for 'reference' objects.

Signed-off-by: Michael Glavassevich <mrglavas@ca.ibm.com>
---
 .../microprofile/openapi/models/PathItem.java | 24 +---------
 .../openapi/models/Reference.java             | 47 +++++++++++++++++++
 .../openapi/models/examples/Example.java      | 25 +---------
 .../openapi/models/headers/Header.java        | 28 +----------
 .../openapi/models/links/Link.java            | 25 +---------
 .../openapi/models/parameters/Parameter.java  | 27 +----------
 .../models/parameters/RequestBody.java        | 29 +-----------
 .../openapi/models/responses/ApiResponse.java | 28 +----------
 .../models/security/SecurityScheme.java       | 35 +-------------
 9 files changed, 62 insertions(+), 206 deletions(-)
 create mode 100644 api/src/main/java/org/eclipse/microprofile/openapi/models/Reference.java

diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
index 95ac5b235..9591c4489 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java
@@ -38,7 +38,7 @@
  *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathItemObject">
  *      OpenAPI Specification Path Item Object</a>
  */
-public interface PathItem extends Constructible, Extensible {
+public interface PathItem extends Constructible, Extensible, Reference<PathItem> {
 
 	/**
 	 * All of the possible types of HTTP operations for this path
@@ -348,26 +348,4 @@ enum HttpMethod {
 	 **/
 	PathItem addParametersItem(Parameter parametersItem);
 
-	/**
-	 * Returns the reference property from this PathItem instance.
-	 *
-	 * @return a reference to a path object in the components in this OpenAPI document
-	 **/
-	String getReference();
-
-	/**
-	 * Sets this PathItem's reference property to the given string.
-	 *
-	 * @param reference  a reference to a path object in the components in this OpenAPI document
-	 **/
-	void setReference(String reference);
-
-	/**
-	 * Sets this PathItem's reference property to the given string.
-	 *
-	 * @param reference  a reference to a path object in the components in this OpenAPI document
-	 * @return the current PathItem instance
-	 **/
-	PathItem reference(String reference);
-
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/Reference.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/Reference.java
new file mode 100644
index 000000000..1bde190d0
--- /dev/null
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Reference.java
@@ -0,0 +1,47 @@
+/**
+ * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright 2017 SmartBear Software
+ * <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.models;
+
+/**
+ * Base interface for OpenAPI model objects that can be references to other objects.
+ */
+public interface Reference<T extends Reference<T>> {
+	
+	/**
+	 * Returns the reference property from this Reference instance.
+	 *
+	 * @return a reference to a T object in the components in this OpenAPI document
+	 **/
+	String getRef();
+
+	/**
+	 * Sets this Reference's reference property to the given string.
+	 *
+	 * @param ref a reference to a T object in the components in this OpenAPI document
+	 **/
+	void setRef(String ref);
+
+	/**
+	 * Sets this Reference's reference property to the given string.
+	 *
+	 * @param ref a reference to a T object in the components in this OpenAPI document
+	 * @return the current instance
+	 **/
+	T ref(String ref);
+
+}
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
index f512e61a6..1f5900275 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java
@@ -19,6 +19,7 @@
 
 import org.eclipse.microprofile.openapi.models.Constructible;
 import org.eclipse.microprofile.openapi.models.Extensible;
+import org.eclipse.microprofile.openapi.models.Reference;
 
 /**
  * Example
@@ -34,7 +35,7 @@
  *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#exampleObject">OpenAPI
  *      Specification Example Object</a>
  */
-public interface Example extends Constructible, Extensible {
+public interface Example extends Constructible, Extensible, Reference<Example> {
 
 	/**
 	 * Returns the summary property from an Example instance.
@@ -128,26 +129,4 @@ public interface Example extends Constructible, Extensible {
 	 */
 	Example externalValue(String externalValue);
 
-	/**
-	 * Returns the reference property from an Example instance.
-	 *
-	 * @return a reference to an example object in the components in this OpenAPI document
-	 */
-	String getReference();
-
-	/**
-	 * Sets this Example's reference property to the given string.
-	 *
-	 * @param reference  a reference to an example object in the components in this OpenAPI document
-	 */
-	void setReference(String reference);
-
-	/**
-	 * Sets this Example's reference property to the given string.
-	 *
-	 * @param reference  a reference to an example object in the components in this OpenAPI document
-	 * @return the current Example object
-	 */
-	Example reference(String reference);
-
 }
\ No newline at end of file
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 e255a0866..9e48443bf 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
@@ -21,6 +21,7 @@
 
 import org.eclipse.microprofile.openapi.models.Constructible;
 import org.eclipse.microprofile.openapi.models.Extensible;
+import org.eclipse.microprofile.openapi.models.Reference;
 import org.eclipse.microprofile.openapi.models.examples.Example;
 import org.eclipse.microprofile.openapi.models.media.Content;
 import org.eclipse.microprofile.openapi.models.media.Schema;
@@ -35,7 +36,7 @@
  *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#header-object">OpenAPI
  *      Specification Header Object</a>
  */
-public interface Header extends Constructible, Extensible {
+public interface Header extends Constructible, Extensible, Reference<Header> {
 	
     /**
      * Controls the style of serialization. Only one style is supported for headers.
@@ -298,29 +299,4 @@ public String toString() {
 	 */
 	Header content(Content content);
 
-	/**
-	 * Returns the reference property from a Header instance.
-	 *
-	 * @return a reference to a header object in an OpenAPI document especially
-	 *         in the components in this OpenAPI document
-	 */
-	String getReference();
-
-	/**
-	 * Sets this Header's reference property to the given string.
-	 *
-	 * @param reference  a reference to a header object in an OpenAPI document
-	 *            especially in the components in this OpenAPI document
-	 */
-	void setReference(String reference);
-
-	/**
-	 * Sets this Header's reference property to the given string.
-	 *
-	 * @param reference  a reference to a header object in an OpenAPI document
-	 *            especially in the components in this OpenAPI document
-	 * @return the current Header instance
-	 */
-	Header reference(String reference);
-
 }
\ No newline at end of file
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 4e59d42e0..c37121ab1 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
@@ -21,6 +21,7 @@
 
 import org.eclipse.microprofile.openapi.models.Constructible;
 import org.eclipse.microprofile.openapi.models.Extensible;
+import org.eclipse.microprofile.openapi.models.Reference;
 import org.eclipse.microprofile.openapi.models.parameters.RequestBody;
 import org.eclipse.microprofile.openapi.models.servers.Server;
 
@@ -46,7 +47,7 @@
  *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#linkObject">
  *      OpenAPI Specification Link Object</a>
  */
-public interface Link extends Constructible, Extensible {
+public interface Link extends Constructible, Extensible, Reference<Link> {
 
 	/**
 	 * Returns the server property from a Link instance.
@@ -199,26 +200,4 @@ public interface Link extends Constructible, Extensible {
 	 */
 	Link description(String description);
 
-	/**
-	 * Returns the reference property from a Link instance.
-	 *
-	 * @return a reference to one of the components in this OpenAPI document
-	 **/
-	String getReference();
-
-	/**
-	 * Sets this Link's reference property to the given string.
-	 *
-	 * @param reference  a reference to a link object in the components in this OpenAPI document
-	 **/
-	void setReference(String reference);
-
-	/**
-	 * Sets this Link's reference property to the given string.
-	 *
-	 * @param reference  a reference to a link object in the components in this OpenAPI document
-	 * @return the current Link instance
-	 */
-	Link reference(String reference);
-
 }
\ No newline at end of file
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 08f8298ed..cf6b85bcc 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
@@ -20,6 +20,7 @@
 import java.util.Map;
 
 import org.eclipse.microprofile.openapi.models.Extensible;
+import org.eclipse.microprofile.openapi.models.Reference;
 import org.eclipse.microprofile.openapi.models.examples.Example;
 import org.eclipse.microprofile.openapi.models.media.Content;
 import org.eclipse.microprofile.openapi.models.media.Schema;
@@ -55,7 +56,7 @@
  *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameterObject">OpenAPI
  *      Specification Parameter Object</a>
  */
-public interface Parameter extends Extensible {
+public interface Parameter extends Extensible, Reference<Parameter> {
 
 	/**
 	 * The values allowed for the style field.
@@ -396,28 +397,4 @@ public String toString() {
 	 */
 	Parameter content(Content content);
 
-	/**
-	 * Returns the reference property from a Parameter instance.
-	 *
-	 * @return  a reference to a parameter object in an OpenAPI document
-	 **/
-	String getReference();
-
-	/**
-	 * Sets reference property of a Parameter instance to the given string.
-	 *
-	 * @param reference  a reference to a header object in an OpenAPI document
-	 *            especially in the components in this OpenAPI document
-	 */
-	void setReference(String reference);
-
-	/**
-	 * Sets reference property of a Parameter instance to the given string.
-	 *
-	 * @param reference  a reference to a header object in an OpenAPI document
-	 *            especially in the components in this OpenAPI document
-	 * @return the current Parameter instance
-	 */
-	Parameter reference(String reference);
-
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java
index 207820181..b563fb4ee 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java
@@ -19,6 +19,7 @@
 
 import org.eclipse.microprofile.openapi.models.Constructible;
 import org.eclipse.microprofile.openapi.models.Extensible;
+import org.eclipse.microprofile.openapi.models.Reference;
 import org.eclipse.microprofile.openapi.models.media.Content;
 
 /**
@@ -26,7 +27,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#requestBodyObject"
  */
-public interface RequestBody extends Constructible, Extensible {
+public interface RequestBody extends Constructible, Extensible, Reference<RequestBody> {
 
 	/**
 	 * Returns the description of this instance of RequestBody.
@@ -108,30 +109,4 @@ public interface RequestBody extends Constructible, Extensible {
 
 	RequestBody required(Boolean required);
 
-	/**
-	 * Returns the reference to this RequestBody instance that is defined.
-	 *
-	 * @return the reference to the response
-	 **/
-
-	String getRef();
-
-	/**
-	 * Sets the reference to this RequestBody instance that is defined.
-	 *
-	 * @param ref the reference to the response
-	 */
-
-	void setRef(String ref);
-
-	/**
-	 * Sets the reference to this RequestBody instance that is defined
-	 * and returns this instance of RequestBody.
-	 *
-	 * @param ref the reference to the response
-	 * @return this RequestBody instance
-	 */
-
-	RequestBody ref(String ref);
-
 }
\ No newline at end of file
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 c2e9ec3bb..10b5dfd0a 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
@@ -21,6 +21,7 @@
 
 import org.eclipse.microprofile.openapi.models.Constructible;
 import org.eclipse.microprofile.openapi.models.Extensible;
+import org.eclipse.microprofile.openapi.models.Reference;
 import org.eclipse.microprofile.openapi.models.headers.Header;
 import org.eclipse.microprofile.openapi.models.links.Link;
 import org.eclipse.microprofile.openapi.models.media.Content;
@@ -31,7 +32,7 @@
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#responseObject"
  */
-public interface ApiResponse extends Constructible, Extensible {
+public interface ApiResponse extends Constructible, Extensible, Reference<ApiResponse> {
 
 	/**
 	 * Returns a short description of this instance of ApiResponse.
@@ -153,29 +154,4 @@ public interface ApiResponse extends Constructible, Extensible {
 
 	ApiResponse link(String name, Link link);
 
-	/**
-	 * Returns the reference to this ApiResponse instance that is defined.
-	 *
-	 * @return the reference to the response
-	 **/
-	String getRef();
-
-	/**
-	 * Sets the reference to this ApiResponse instance that is defined.
-	 *
-	 * @param ref the reference to the response
-	 */
-
-	void setRef(String ref);
-
-	/**
-	 * Sets the reference to this ApiResponse instance that is defined and
-	 * returns this instance of ApiResponse.
-	 *
-	 * @param ref the reference to the response
-	 * @return this ApiResponse instance
-	 */
-
-	ApiResponse ref(String ref);
-
 }
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java
index 5bc7d7550..e500d1bf0 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java
@@ -19,13 +19,14 @@
 
 import org.eclipse.microprofile.openapi.models.Constructible;
 import org.eclipse.microprofile.openapi.models.Extensible;
+import org.eclipse.microprofile.openapi.models.Reference;
 
 /**
  * SecurityScheme
  *
  * @see "https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#securitySchemeObject"
  */
-public interface SecurityScheme extends Constructible, Extensible {
+public interface SecurityScheme extends Constructible, Extensible, Reference<SecurityScheme> {
 
 	/**
 	 * Type is a REQUIRED property that specifies the type of SecurityScheme instance.
@@ -360,36 +361,4 @@ public String toString() {
 
 	SecurityScheme openIdConnectUrl(String openIdConnectUrl);
 
-	/**
-	 * ref property is the reference of the model's location.
-	 * <p>
-	 * This method returns the ref property from SecurityScheme instance.
-	 * <p>
-	 * @return String ref
-	 **/
-	String getRef();
-
-	/**
-	 * ref property is the reference of the model's location.
-	 * <p>
-	 * This method sets the ref property of SecurityScheme instance
-	 * to the given String argument.
-	 *
-	 * @param ref
-	 */
-
-	void setRef(String ref);
-
-	/**
-	 * ref property is the reference of the model's location.
-	 * <p>
-	 * This method sets the ref property of SecurityScheme instance
-	 * to the given String argument and returns the modified instance.
-	 *
-	 * @param ref
-	 * @return SecurityScheme instance with the set ref property
-	 */
-
-	SecurityScheme ref(String ref);
-
 }
\ No newline at end of file