Updated javadocs

Author: webron

modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiImplicitParam.java

@@ -65,7 +65,8 @@
    * <li>To set a list of values, provide a comma-separated list.
    * For example: {@code first, second, third}.</li>
    * <li>To set a range of values, start the value with "range", and surrounding by square
-   * brackets include the minimum and maximum values. For example: {@code range[1, 5]}.</li>
+   * brackets include the minimum and maximum values, or round brackets for exclusive minimum and maximum values.
+   * For example: {@code range[1, 5]}, {@code range(1, 5)}, {@code range[1, 5)}.</li>
    * <li>To set a minimum/maximum value, use the same format for range but use "infinity"
    * or "-infinity" as the second value. For example, {@code range[1, infinity]} means the
    * minimum allowable value of this parameter is 1.</li>

modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiModelProperty.java

@@ -40,14 +40,15 @@
   String name() default "";
 
   /**
-   * Limits the acceptable values for this property.
+   * Limits the acceptable values for this parameter.
    * <p>
    * There are three ways to describe the allowable values:
    * <ol>
    * <li>To set a list of values, provide a comma-separated list.
    * For example: {@code first, second, third}.</li>
    * <li>To set a range of values, start the value with "range", and surrounding by square
-   * brackets include the minimum and maximum values. For example: {@code range[1, 5]}.</li>
+   * brackets include the minimum and maximum values, or round brackets for exclusive minimum and maximum values.
+   * For example: {@code range[1, 5]}, {@code range(1, 5)}, {@code range[1, 5)}.</li>
    * <li>To set a minimum/maximum value, use the same format for range but use "infinity"
    * or "-infinity" as the second value. For example, {@code range[1, infinity]} means the
    * minimum allowable value of this parameter is 1.</li>

modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiParam.java

@@ -55,15 +55,13 @@
   /**
    * Limits the acceptable values for this parameter.
    * <p>
-   * If the original parameter type is an enum, the values of the enum would be translated to
-   * the allowableValues. Those can be overridden by setting this property.
-   * <p>
    * There are three ways to describe the allowable values:
    * <ol>
    * <li>To set a list of values, provide a comma-separated list.
    * For example: {@code first, second, third}.</li>
    * <li>To set a range of values, start the value with "range", and surrounding by square
-   * brackets include the minimum and maximum values. For example: {@code range[1, 5]}.</li>
+   * brackets include the minimum and maximum values, or round brackets for exclusive minimum and maximum values.
+   * For example: {@code range[1, 5]}, {@code range(1, 5)}, {@code range[1, 5)}.</li>
    * <li>To set a minimum/maximum value, use the same format for range but use "infinity"
    * or "-infinity" as the second value. For example, {@code range[1, infinity]} means the
    * minimum allowable value of this parameter is 1.</li>

modules/swagger-annotations/src/main/java/io/swagger/annotations/Contact.java

@@ -24,27 +24,31 @@
 /**
  * Contact metadata available within the info section of a Swagger definition - see
  * https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#contactObject
+ *
+ * @since 1.5.0
  */
-
 @Target(ElementType.ANNOTATION_TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Contact {
 
     /**
+     * The name of the contact.
+     *
      * @return the name of the contact
      */
-
     String name();
 
     /**
+     * Optional URL associated with this contact.
+     *
      * @return an optional URL associated with this contact
      */
-
     String url() default "";
 
     /**
+     * Optional email for this contact.
+     *
      * @return an optional email for this contact
      */
-
     String email() default "";
 }

modules/swagger-annotations/src/main/java/io/swagger/annotations/Extension.java

@@ -23,22 +23,25 @@
 
 /**
  * An optionally named list of extension properties.
+ *
+ * @since 1.5.0
  */
-
 @Target(ElementType.ANNOTATION_TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Extension {
 
     /**
+     * An option name for these extensions.
+     *
      * @return an option name for these extensions - will be prefixed with "x-"
      */
-
     String name() default "";
 
     /**
+     * The extension properties.
+     *
      * @see ExtensionProperty
      * @return the actual extension properties
      */
-
     ExtensionProperty[] properties();
 }

modules/swagger-annotations/src/main/java/io/swagger/annotations/ExtensionProperty.java

@@ -25,21 +25,23 @@
  * A name/value property within a Swagger extension
  *
  * @see Extension
+ * @since 1.5.0
  */
-
 @Target(ElementType.ANNOTATION_TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ExtensionProperty {
 
     /**
+     * The name of the property.
+     *
      * @return the name of the property
      */
-
     String name();
 
     /**
+     * The value of the property.
+     *
      * @return the value of the property
      */
-
     String value();
 }

modules/swagger-annotations/src/main/java/io/swagger/annotations/ExternalDocs.java

@@ -23,8 +23,8 @@
 
 /**
  * Represents an external documentation description.
- * 
- * @since 1.5.2-M1
+ *
+ * @since 1.5.0
  */
 @Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)

modules/swagger-annotations/src/main/java/io/swagger/annotations/Info.java

@@ -24,53 +24,60 @@
 /**
  * High-level metadata for a Swagger definition - see
  * https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#infoObject
+ *
+ * @since 1.5.0
  */
-
 @Target(ElementType.ANNOTATION_TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Info {
 
     /**
+     * The title of the API.
+     *
      * @return the title of the API
      */
-
     String title();
 
     /**
+     * The version of your API.
+     *
      * @return the version of your API
      */
-
     String version();
 
     /**
+     * An optional description of the API.
+     *
      * @return an optional description of the API
      */
-
     String description() default "";
 
     /**
+     * An optional terms of service for this API.
+     *
      * @return an optional terms of service for this API
      */
-
     String termsOfService() default "";
 
     /**
+     * Optional contact information for this API.
+     *
      * @return optional contact information for this API
      */
-
     Contact contact() default @Contact( name = "");
 
     /**
+     * Optional license information for this API.
+     *
      * @return optional license information for this API
      */
-
     License license() default @License( name = "" );
 
     /**
+     * Optional list of extensions for this API.
+     *
      * @see Extension
      * @return optional list of extensions for this API
      */
-
-
     Extension[] extensions() default @Extension( properties = @ExtensionProperty(name="",value=""));
 }

modules/swagger-annotations/src/main/java/io/swagger/annotations/License.java

@@ -24,21 +24,25 @@
 /**
  * License metadata available within the info section of a Swagger definition, see
  * https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#licenseObject
+ *
+ * @since 1.5.0
  */
 
 @Target(ElementType.ANNOTATION_TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface License {
 
     /**
+     * The name of the license.
+     *
      * @return the name of the license
      */
-
     String name();
 
     /**
+     * An optional URL for the license.
+     *
      * @return an optional URL for the license.
      */
-
     String url() default "";
 }

modules/swagger-annotations/src/main/java/io/swagger/annotations/SwaggerDefinition.java

@@ -28,83 +28,84 @@
  * - Security Requirements
  * - Parameters
  * - Responses
+ *
+ * @since 1.5.0
  */
-
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
 public @interface SwaggerDefinition {
 
     /**
+     * The host to specify in the generated Swagger definition.
+     *
      * @return the host to specify in the generated Swagger definition - keep empty for default
      */
-
     String host() default "";
 
     /**
+     * The basePath to specify in the generated Swagger definition.
+     *
      * @return the basePath to specify in the generated Swagger definition - keep empty for default
      */
-
     String basePath() default "";
 
     /**
-     * Global level consumes for this swagger definition, will be added to all api definitions that
-     * don't have local overrides - see
+     * Global level consumes for this swagger definition.
+     * <p>
+     * These will be added to all api definitions that don't have local overrides - see
      * https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#swagger-object
      *
-     * @return a list of global level consumes
+     * @return a list of global level consumes.
      */
-
     String [] consumes() default "";
 
     /**
-     * Global level produces for this swagger definition, will be added to all api definitions that
-     * don't have local overrides - see
+     * Global level produces for this swagger definition.
+     * <p>
+     * These will be added to all api definitions that don't have local overrides - see
      * https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#swagger-object
      *
      * @return a list of global level consumes
      */
-
     String [] produces() default "";
 
     /**
-     * The transfer protocol of the API. Setting this to Scheme.DEFAULT will result in
-     * the result being generated from the hosting container.
+     * The transfer protocol of the API.
+     * <p>
+     * Setting this to Scheme.DEFAULT will result in the result being generated from the hosting container.
      *
      * @return list of supported transfer protocols, keep empty for default
      */
-
     Scheme [] schemes() default Scheme.DEFAULT;
 
     /**
      * Enumeration with valid schemes
      */
-
     enum Scheme { DEFAULT, HTTP, HTTPS, WS, WSS };
 
     /**
-     * Global tags that can be used to tag inidividual Apis and ApiOperations. See
-     * https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#tagObject
+     * Global tags that can be used to tag individual Apis and ApiOperations.
+     * <p>
+     * See https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#tagObject
      *
      * @return list of globally defined tags
      */
-
     Tag [] tags() default @Tag( name = "" );
 
     /**
-     * General metadata for this Swagger definition. See
-     * https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#infoObject
+     * General metadata for this Swagger definition.
+     * <p>
+     * See https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#infoObject
      *
      * @return general metadata for this Swagger definition
      */
-
     Info info() default @Info( title = "", version = "" );
 
     /**
-     * Reference to external documentation for this Swagger definition
+     * Reference to external documentation for this Swagger definition.
      *
      * @return a reference to external documentation
      */
-
     ExternalDocs externalDocs() default @ExternalDocs( url = "");
 }