Merge branch 'develop_2.0'

Author: fehguy

LICENSE

@@ -1,4 +1,4 @@
-Copyright 2015 Reverb Technologies, Inc.
+Copyright 2015 SmartBear Software
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

README.md

@@ -29,7 +29,7 @@ The Swagger Specification has undergone 3 revisions since initial creation in 20
 
 Swagger core Version      | Release Date | Swagger Spec compatibility | Notes | Status
 ------------------------- | ------------ | -------------------------- | ----- | ----
-1.5.1-M2                  | 2015-04-05   | 2.0           | [master](https://github.com/swagger-api/swagger-core) | Supported
+1.5.2-M2                  | 2015-04-05   | 2.0           | [master](https://github.com/swagger-api/swagger-core) | Supported
 1.3.12                    | 2014-12-23   | 1.2           | [tag v1.3.12](https://github.com/swagger-api/swagger-core/tree/v1.3.12) | Supported
 1.2.4                     | 2013-06-19   | 1.1           | [tag swagger-project_2.10.0-1.2.4](https://github.com/swagger-api/swagger-core/tree/swagger-project_2.10.0-1.2.4) | Deprecated
 1.0.0                     | 2011-10-16   | 1.0           | [tag v1.0](https://github.com/swagger-api/swagger-core/tree/v1.0) | Deprecated
@@ -38,7 +38,7 @@ Swagger core Version      | Release Date | Swagger Spec compatibility | Notes |
 To allow independent development, scala support has been moved into a separate project.  See the [swagger-scala-module](https://github.com/swagger-api/swagger-scala-module) for details.  Play! framework support is moving outside the swagger-core project as well.
 
 ## Overview
-This is a project to build the swagger-core library, which is required for the Reverb implementation of the Swagger spec. 
+This is a project to build the swagger-core library, which is required for the Swagger implementation of the Swagger spec. 
 
 ### Change History
 If you're interested in the change history of swagger and the swagger-core framework, see [here](https://github.com/swagger-api/swagger-core/wiki/Changelog).
@@ -52,7 +52,7 @@ You need the following installed and available in your $PATH:
 * Jackson 2.4.2 or greater
 
 
-### To build from source (currently 1.5.1-M2)
+### To build from source (currently 1.5.2-M2)
 ```
 # first time building locally
 mvn -N
@@ -81,7 +81,7 @@ There are a number of sample apps in the [samples](https://github.com/swagger-ap
 License
 -------
 
-Copyright 2015 Reverb Technologies, Inc.
+Copyright 2015 SmartBear Software
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

modules/swagger-annotations/pom.xml

@@ -3,13 +3,13 @@
   <parent>
     <groupId>com.wordnik</groupId>
     <artifactId>swagger-project</artifactId>
-    <version>1.5.1-M2</version>
+    <version>1.5.2-M2</version>
     <relativePath>../..</relativePath>
   </parent>
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.wordnik</groupId>
   <artifactId>swagger-annotations</artifactId>
-  <version>1.5.1-M2</version>
+  <version>1.5.2-M2</version>
   <packaging>bundle</packaging>
   <name>swagger-annotations</name>
 

modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/Api.java

@@ -1,5 +1,5 @@
 /**
- *  Copyright 2015 Reverb Technologies, Inc.
+ *  Copyright 2015 SmartBear Software
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -22,10 +22,7 @@
 /**
  * Marks a class as a Swagger resource.
  * <p>
- * The resource affects both the root document of Swagger, the Resource
- * Listing, and the API Declaration of that specific resource.
- * <p>
- * Swagger will only include and introspect only classes that are annotated
+ * By default, Swagger-Core will only include and introspect only classes that are annotated
  * with {@code @Api} and will ignore other resources (JAX-RS endpoints, Servlets and
  * so on).
  */
@@ -34,85 +31,77 @@
 @Inherited
 public @interface Api {
   /**
-   * The 'path' that is going to be used to host the API Declaration of the
-   * resource.
+   * Implicitly sets a tag for the operations, legacy support (read description).
    * <p>
-   * For JAX-RS resources, this would normally have the same value as the {@code @Path}
-   * on the resource, but can be any other value as well. It will serve as the path
-   * where the documentation is hosted.
+   * In swagger-core 1.3.X, this was used as the 'path' that is to host the API Declaration of the
+   * resource. This is no longer relevant in swagger-core 1.5.X.
    * <p>
-   * For Servlets, this path has to be the path serving the Servlet.
+   * If {@link #tags()} is <i>not</i> used, this value will be used to set the tag for the operations described by this
+   * resource. Otherwise, the value will be ignored.
    * <p>
-   * If the value isn't preceded with a slash, one would be added to it.
-   * 
-   * @return the document location value, or empty string if not set
+   * The leading / (if exists) will be removed.
+   *
+   * @return tag name for operations under this resource, unless {@link #tags()} is defined.
    */
   String value() default "";
 
   /**
    * A list of tags for API documentation control. 
    * Tags can be used for logical grouping of operations by resources or any other qualifier.
+   * <p>
+   * A non-empty value will override the value provided in {@link #value()}.
    * 
-   * @since 1.5.2
+   * @since 1.5.2-M1
    *
    * @return a string array of tag values
    */
   String[] tags() default "";
 
   /**
-   * Corresponds to the `description` field of the Resource Listing API operation.
-   * <p>
-   * This should be a short description of the resource.
+   * Not used in 1.5.X, kept for legacy support.
    *
-   * @return a longer description about this API
+   * @return a longer description about this API, no longer used.
    */
+  @Deprecated
   String description() default "";
 
   /**
-   * Corresponds to the `basePath` field of the API Declaration.
-   * <p>
-   * The `basePath` is derived automatically by Swagger. This property allows
-   * overriding the default value if needed.  for swagger 2.0 specifications, this
-   * value is no longer supported
-   *
-   * @since 1.3.7
+   * Not used in 1.5.X, kept for legacy support.
    *
-   * @return the basePath for this operation
+   * @return the basePath for this operation, no longer used.
    */
   @Deprecated
   String basePath() default "";
 
   /**
-   * Optional explicit ordering of this API resource in the Resource Listing.
-   * As of swagger-spec 2.0, this value is no longer used
-   *
+   * Not used in 1.5.X, kept for legacy support.
    *
-   * @return the position of this API in the resource listing
+   * @return the position of this API in the resource listing, no longer used.
    */
   @Deprecated
   int position() default 0;
 
   /**
-   * Corresponds to the `produces` field of the API Declaration.
+   * Corresponds to the `produces` field of the operations under this resource.
    * <p>
    * Takes in comma-separated values of content types.
-   * For example, "application/json, application/xml" would suggest this API Resource
-   * generates JSON and XML output.
+   * For example, "application/json, application/xml" would suggest the operations
+   * generate JSON and XML output.
    * <p>
    * For JAX-RS resources, this would automatically take the value of the {@code @Produces}
    * annotation if such exists. It can also be used to override the {@code @Produces} values
    * for the Swagger documentation.
    *
-   * @return the supported media types supported by the server, or an empty string if not set
+   * @return the supported media types supported by the server, or an empty string if not set.
    */
   String produces() default "";
 
   /**
-   * Corresponds to the `consumes` field of the API Declaration.
+   * Corresponds to the `consumes` field of the operations under this resource.
    * <p>
    * Takes in comma-separated values of content types.
-   * For example, "application/json, application/xml" would suggest this API Resource
-   * accepts JSON and XML input.
+   * For example, "application/json, application/xml" would suggest the operations
+   * accept JSON and XML input.
    * <p>
    * For JAX-RS resources, this would automatically take the value of the {@code @Consumes}
    * annotation if such exists. It can also be used to override the {@code @Consumes} values
@@ -123,28 +112,28 @@
   String consumes() default "";
 
   /**
-   * This property is currently not in use.
+   * Sets specific protocols (schemes) for the operations under this resource.
+   * <p>
+   * Comma-separated values of the available protocols. Possible values: http, https, ws, wss.
    * 
-   * @return the protocols supported by the server
+   * @return the protocols supported by the operations under the resource.
    */
   String protocols() default "";
 
   /**
-   * Corresponds to the `authorizations` field of the API Declaration.
+   * Corresponds to the `security` field of the Operation Object.
    * <p>
-   * Takes in a list of the required authorizations for this API Resource.
+   * Takes in a list of the authorizations (security requirements) for the operations under this resource.
    * This may be overridden by specific operations.
    *
    * @see Authorization
    *
-   * @return an array of authorizations required by the server, or a single, empty authorization value if not set
+   * @return an array of authorizations required by the server, or a single, empty authorization value if not set.
    */
-  Authorization[] authorizations() default @Authorization(value = "", type = "");
+  Authorization[] authorizations() default @Authorization(value = "");
 
   /**
-   * Hides the api.
-   *
-   * @since 1.3.8
+   * Hides the operations under this resource.
    *
    * @return true if the api should be hidden from the swagger documentation
    */

modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiImplicitParam.java

@@ -1,5 +1,5 @@
 /**
- *  Copyright 2015 Reverb Technologies, Inc.
+ *  Copyright 2015 SmartBear Software
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -41,7 +41,6 @@
    * For proper Swagger functionality, follow these rules when naming your parameters based on {@link #paramType()}:
    * <ol>
    * <li>If {@code paramType} is "path", the name should be the associated section in the path.</li>
-   * <li>If {@code paramType} is "body", the name should be "body".</li>
    * <li>For all other cases, the name should be the parameter name as your application expects to accept.</li>
    * </ol>
    *
@@ -64,8 +63,8 @@
    * <p>
    * There are three ways to describe the allowable values:
    * <ol>
-   * <li>To set a list of values, provide a comma-separated list surrounded by square brackets.
-   * For example: {@code [first, second, third]}.</li>
+   * <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>
    * <li>To set a minimum/maximum value, use the same format for range but use "infinity"
@@ -84,11 +83,13 @@
 
   /**
    * Allows for filtering a parameter from the API documentation.
+   *<p>
+   * See com.wordnik.swagger.core.filter.SwaggerSpecFilter for further details.
    */
   String access() default "";
 
   /**
-   * Specifies whether the parameter can accept multiple comma-separated values.
+   * Specifies whether the parameter can accept multiple values by having multiple occurrences.
    */
   boolean allowMultiple() default false;
 

modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiImplicitParams.java

@@ -1,5 +1,5 @@
 /**
- *  Copyright 2015 Reverb Technologies, Inc.
+ *  Copyright 2015 SmartBear Software
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.

modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiModel.java

@@ -1,5 +1,5 @@
 /**
- *  Copyright 2015 Reverb Technologies, Inc.
+ *  Copyright 2015 SmartBear Software
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.

modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiModelProperty.java

@@ -1,5 +1,5 @@
 /**
- *  Copyright 2015 Reverb Technologies, Inc.
+ *  Copyright 2015 SmartBear Software
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -21,73 +21,80 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-/** 
- * An ApiModelProperty desecribes a property inside a model class.  The annotations can
- * apply to a method, a property, etc., depending on how the model scanner is configured and
- * used.
+/**
+ * Adds and manipulates data of a model property.
  */
 @Target({ElementType.METHOD, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ApiModelProperty {
-  /** Provide a human readable synopsis of this property */
+  /**
+   * A brief description of this property.
+   */
   String value() default "";
 
   /**
-   * Allows overriding the name of the property
+   * Allows overriding the name of the property.
    *
    * @return the overridden property name
    */
   String name() default "";
 
   /**
-   * If the values that can be set are restricted, they can be set here. In the form of a comma separated list
-   * <code>registered, active, closed</code>.
-   *
-   * @return the allowable values
+   * Limits the acceptable values for 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>
+   * <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>
+   * </ol>
    */
   String allowableValues() default "";
 
-  /** 
-   * specify an optional access value for filtering in a Filter 
-   * implementation.  This
-   * allows you to hide certain parameters if a user doesn't have access to them
+  /**
+   * Allows for filtering a property from the API documentation. See com.wordnik.swagger.core.filter.SwaggerSpecFilter.
    */
   String access() default "";
 
-  /** long description of the property */
+  /**
+   * Currently not in use.
+   */
   String notes() default "";
 
   /**
-   * The dataType. See the documentation for the supported datatypes. If the data type is a custom object, set
-   * it's name, or nothing. In case of an enum use 'string' and allowableValues for the enum constants.
+   * The data type of the parameter.
+   * <p>
+   * This can be the class name or a primitive. The value will override the data type as read from the class
+   * property.
    */
   String dataType() default "";
 
   /**
-   * Whether or not the property is required, defaults to false.
-   * 
-   * @return true if required, false otherwise
+   * Specifies if the parameter is required or not.
    */
   boolean required() default false;
 
   /**
-   * allows explicitly ordering the property in the model.  Since reflection has no guarantee on
-   * ordering, you should specify property order to keep models consistent across different VM implementations and versions.
+   * Allows explicitly ordering the property in the model.
    */
   int position() default 0;
-  
+
   /**
-   * Allows a model property to be marked as hidden in the swagger model definition
+   * Allows a model property to be hidden in the Swagger model definition.
    */
   boolean hidden() default false;
 
   /**
-   * A sample value for the property
-   **/
+   * A sample value for the property.
+   */
   String example() default "";
 
   /**
-   * Allows a model property to be designated as read only
-   **/
+   * Allows a model property to be designated as read only.
+   */
   boolean readOnly() default false;
 }