Ensure map and list getters returns an (immutable) copy

See eclipse#240

Signed-off-by: Jeremie Bresson <dev@jmini.fr>

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

@@ -54,7 +54,7 @@ public interface Components extends Constructible, Extensible<Components> {
     /**
      * Returns the schemas property from a Components instance.
      *
-     * @return a Map containing the keys and the reusable schemas for this OpenAPI document
+     * @return a copy Map (potentially immutable) containing the keys and the reusable schemas for this OpenAPI document
      **/
     Map<String, Schema> getSchemas();
 
@@ -95,7 +95,7 @@ default Components schemas(Map<String, Schema> schemas) {
     /**
      * 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 copy Map (potentially immutable) containing the keys and the reusable responses from API operations for this OpenAPI document
      **/
     Map<String, APIResponse> getResponses();
 
@@ -136,7 +136,7 @@ default Components responses(Map<String, APIResponse> responses) {
     /**
      * 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 copy Map (potentially immutable) containing the keys and the reusable parameters of API operations for this OpenAPI document
      **/
     Map<String, Parameter> getParameters();
 
@@ -177,7 +177,7 @@ default Components parameters(Map<String, Parameter> parameters) {
     /**
      * Returns the examples property from a Components instance.
      *
-     * @return a Map containing the keys and the reusable examples for this OpenAPI document
+     * @return a copy Map (potentially immutable) containing the keys and the reusable examples for this OpenAPI document
      **/
     Map<String, Example> getExamples();
 
@@ -218,7 +218,7 @@ default Components examples(Map<String, Example> examples) {
     /**
      * Returns the requestBodies property from a Components instance.
      *
-     * @return a Map containing the keys and the reusable request bodies for this OpenAPI document
+     * @return a copy Map (potentially immutable) containing the keys and the reusable request bodies for this OpenAPI document
      **/
     Map<String, RequestBody> getRequestBodies();
 
@@ -259,7 +259,7 @@ default Components requestBodies(Map<String, RequestBody> requestBodies) {
     /**
      * Returns the headers property from a Components instance.
      *
-     * @return a Map containing the keys and the reusable headers for this OpenAPI document
+     * @return a copy Map (potentially immutable) containing the keys and the reusable headers for this OpenAPI document
      **/
     Map<String, Header> getHeaders();
 
@@ -300,7 +300,7 @@ default Components headers(Map<String, Header> headers) {
     /**
      * Returns the securitySchemes property from a Components instance.
      *
-     * @return a Map containing the keys and the reusable security schemes for this OpenAPI document
+     * @return a copy Map (potentially immutable) containing the keys and the reusable security schemes for this OpenAPI document
      **/
     Map<String, SecurityScheme> getSecuritySchemes();
 
@@ -341,7 +341,7 @@ default Components securitySchemes(Map<String, SecurityScheme> securitySchemes)
     /**
      * Returns the links property from a Components instance.
      *
-     * @return a Map containing the keys and the reusable links for this OpenAPI document
+     * @return a copy Map (potentially immutable) containing the keys and the reusable links for this OpenAPI document
      **/
     Map<String, Link> getLinks();
 
@@ -382,7 +382,7 @@ default Components links(Map<String, Link> links) {
     /**
      * Returns the callbacks property from a Components instance.
      *
-     * @return a Map containing the keys and the reusable callbacks for this OpenAPI document
+     * @return a copy Map (potentially immutable) containing the keys and the reusable callbacks for this OpenAPI document
      **/
     Map<String, Callback> getCallbacks();
 

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

@@ -111,7 +111,7 @@ default OpenAPI externalDocs(ExternalDocumentation externalDocs) {
     /**
      * Returns the Servers defined in the API
      *
-     * @return Server objects which provide connectivity information to target servers
+     * @return a copy List (potentially immutable) of Server objects which provide connectivity information to target servers
      **/
     List<Server> getServers();
 
@@ -151,7 +151,7 @@ default OpenAPI servers(List<Server> servers) {
     /**
      * Returns the security property from an OpenAPI instance.
      *
-     * @return which security mechanisms can be used across the API
+     * @return a copy List (potentially immutable) containing the security mechanisms that can be used across the API
      **/
     List<SecurityRequirement> getSecurity();
 
@@ -191,7 +191,7 @@ default OpenAPI security(List<SecurityRequirement> security) {
     /**
      * Returns the tags property from an OpenAPI instance.
      *
-     * @return tags used by the specification
+     * @return a copy List (potentially immutable) of tags defined in this the specification
      **/
 
     List<Tag> getTags();

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

@@ -41,7 +41,7 @@ public interface Operation extends Constructible, Extensible<Operation> {
     /**
      * Returns the tags property from an Operation instance.
      *
-     * @return a list of the operation's tags
+     * @return a copy List (potentially immutable) of the operation's tags
      **/
     List<String> getTags();
 
@@ -181,7 +181,7 @@ default Operation operationId(String operationId) {
     /**
      * Returns the parameters property from an Operation instance.
      *
-     * @return a list of parameters that are applicable for this operation
+     * @return a copy List (potentially immutable) of parameters that are applicable for this operation
      **/
     List<Parameter> getParameters();
 
@@ -271,7 +271,7 @@ default Operation responses(APIResponses responses) {
     /**
      * Returns the callbacks property from an Operation instance.
      *
-     * @return map of possible out-of-band callbacks related to the operation
+     * @return a copy Map (potentially immutable) of possible out-of-band callbacks related to the operation
      **/
     Map<String, Callback> getCallbacks();
 
@@ -337,7 +337,7 @@ default Operation deprecated(Boolean deprecated) {
     /**
      * Returns the security property from an Operation instance.
      *
-     * @return a list of which security mechanisms can be used for this operation
+     * @return a copy List (potentially immutable) of which security mechanisms can be used for this operation
      **/
     List<SecurityRequirement> getSecurity();
 
@@ -377,7 +377,7 @@ default Operation security(List<SecurityRequirement> security) {
     /**
      * Returns the servers property from an Operation instance.
      *
-     * @return a list of servers to service this operation
+     * @return a copy List (potentially immutable) of servers to service this operation
      **/
     List<Server> getServers();
 

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

@@ -303,7 +303,7 @@ default PathItem TRACE(Operation trace) {
     /**
      * Returns the servers property from a PathItem instance.
      *
-     * @return a list of all the servers defined in this path item
+     * @return a copy List (potentially immutable) of all the servers defined in this path item
      **/
     List<Server> getServers();
 
@@ -343,7 +343,7 @@ default PathItem servers(List<Server> servers) {
     /**
      * Returns the parameters property from this PathItem instance.
      *
-     * @return a list of parameters that are applicable to all the operations described under this path
+     * @return a copy List (potentially immutable) of parameters that are applicable to all the operations described under this path
      **/
     List<Parameter> getParameters();
 

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

@@ -232,23 +232,23 @@ default Header schema(Schema schema) {
     /**
      * Returns the examples property from a Header instance.
      *
-     * @return examples of the media type
+     * @return a copy Map (potentially immutable) of examples of the header
      **/
     Map<String, Example> getExamples();
 
     /**
      * 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
+     * @param examples examples of the header
      */
     void setExamples(Map<String, Example> examples);
 
     /**
      * 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
+     * @param examples examples of the header
      * @return the current Header instance
      */
     default Header examples(Map<String, Example> examples) {
@@ -257,17 +257,17 @@ default Header examples(Map<String, Example> examples) {
     }
 
     /**
-     * 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
+     * Adds an example of the header 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 example example of the media type
+     * @param example example of the header
      * @return the current Header instance
      */
     Header addExample(String key, Example example);
 
     /**
-     * Removes an example of the media type using the specified key to this Header instance.
+     * Removes an example of the header using the specified key to this Header instance.
      *
      * @param key string to represent the example
      */
@@ -276,23 +276,23 @@ default Header examples(Map<String, Example> examples) {
     /**
      * Returns the example property from a Header instance.
      *
-     * @return example of the media type
+     * @return example of the header
      **/
     Object getExample();
 
     /**
      * 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
+     * @param example example of the header
      */
     void setExample(Object example);
 
     /**
      * 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
+     * @param example example of the header
      * @return the current Header instance
      */
     default Header example(Object example) {

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

@@ -146,7 +146,7 @@ default 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
+     * @return a copy Map (potentially immutable) representing parameters to pass to this link's operation
      **/
     Map<String, Object> getParameters();
 

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

@@ -89,7 +89,7 @@ default Discriminator mapping(Map<String, String> mapping) {
     /**
      * Returns the mapping property from a Discriminator instance.
      *
-     * @return a map containing keys and schema names or references
+     * @return a copy Map (potentially immutable) containing keys and schema names or references
      **/
     Map<String, String> getMapping();
 

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

@@ -97,7 +97,7 @@ default Encoding headers(Map<String, Header> headers) {
      * <p>
      * This method returns the headers property from a Encoding instance.
      * </p>
-     * @return Map&lt;String, Header&gt; headers
+     * @return a copy Map (potentially immutable) containing headers
      **/
     Map<String, Header> getHeaders();
 

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

@@ -62,7 +62,7 @@ default MediaType schema(Schema schema) {
     /**
      * Returns the collection of examples from a MediaType instance.
      *
-     * @return examples of the media type
+     * @return a copy Map (potentially immutable) of examples of the media type
      **/
     Map<String, Example> getExamples();
 
@@ -134,7 +134,7 @@ default MediaType example(Object example) {
     /**
      * Returns the encoding property from a MediaType instance.
      *
-     * @return a map between a property name and its encoding information
+     * @return  a copy Map (potentially immutable) between a property name and its encoding information
      **/
     Map<String, Encoding> getEncoding();
 

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

@@ -139,7 +139,7 @@ default Schema defaultValue(Object defaultValue) {
     /**
      * Returns the enumerated list of values allowed for objects defined by this Schema.
      *
-     * @return the list of values allowed for objects defined by this Schema
+     * @return a copy List (potentially immutable) of values allowed for objects defined by this Schema
      */
     List<Object> getEnumeration();
 
@@ -512,7 +512,7 @@ default Schema minProperties(Integer minProperties) {
     /**
      * Returns the required property from this Schema instance.
      *
-     * @return the list of fields required in objects defined by this Schema
+     * @return a copy List (potentially immutable) of fields required in objects defined by this Schema
      **/
     List<String> getRequired();
 
@@ -604,7 +604,7 @@ default Schema not(Schema not) {
     /**
      * Returns the properties defined in this Schema.
      *
-     * @return a map which associates property names with the schemas that describe their contents
+     * @return a copy Map (potentially immutable) which associates property names with the schemas that describe their contents
      **/
     Map<String, Schema> getProperties();
 
@@ -980,7 +980,7 @@ default Schema items(Schema items) {
     /**
      * Returns the schemas used by the allOf property.
      *
-     * @return the list of schemas used by the allOf property
+     * @return a copy List (potentially immutable) of schemas used by the allOf property
      **/
     List<Schema> getAllOf();
 
@@ -1020,7 +1020,7 @@ default Schema allOf(List<Schema> allOf) {
     /**
      * Returns the schemas used by the anyOf property.
      *
-     * @return the list of schemas used by the anyOf property
+     * @return a copy List (potentially immutable) of schemas used by the anyOf property
      **/
     List<Schema> getAnyOf();
 
@@ -1060,7 +1060,7 @@ default Schema anyOf(List<Schema> anyOf) {
     /**
      * Returns the schemas used by the oneOf property.
      *
-     * @return the list of schemas used by the oneOf property
+     * @return a copy List (potentially immutable) of schemas used by the oneOf property
      **/
     List<Schema> getOneOf();