Merge branch 'develop_2.0'

Author: fehguy

.gitignore

@@ -9,4 +9,5 @@ samples/scala-play2/logs
 .classpath
 .cache
 atlassian-ide-plugin.xml
-*.iml
+*.iml
+.java-version

.travis.yml

@@ -1,5 +1,6 @@
+sudo: false
 language: java
-script: mvn verify
+script: mvn clean verify
 jdk:
   - oraclejdk7
 

README.md

@@ -1,10 +1,10 @@
 # Swagger Core library
 
-[![Build Status](https://travis-ci.org/swagger-api/swagger-core.png?branch=master)](https://travis-ci.org/swagger-api/swagger-core)
+[![Build Status](https://travis-ci.org/swagger-api/swagger-core.svg?branch=develop_2.0)](https://travis-ci.org/swagger-api/swagger-core)
 
 The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service.
 
-Swagger-core is the Java/Scala implementation of Swagger. It supports *JAX-RS*, *plain Servlets*, and *Play Framework*.
+Swagger-core is the Java implementation of Swagger. Current version supports *JAX-RS*. Future milestone releases will add support for *plain Servlets* and *Play Framework*.
 
 Check out [Swagger-Spec](https://github.com/swagger-api/swagger-spec) for additional information about the Swagger project, including additional libraries with support for SpringMVC, other languages and more. 
 
@@ -20,22 +20,20 @@ The following methods are available to obtain support for Swagger:
 
 
 ## Get started with Swagger!
-See the guide on [getting started with swagger](https://github.com/swagger-api/swagger-core/wiki/Adding-Swagger-to-your-API) to get started with adding swagger to your API.
+See the guide on [getting started with swagger](https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-JAX-RS-Project-Setup) to get started with adding swagger to your API.
 
 ## Compatibility
 The Swagger Specification has undergone 3 revisions since initial creation in 2010.  The swagger-core project has the following compatibilities with the swagger specification:
 
 Swagger core Version      | Release Date | Swagger Spec compatibility | Notes | Status
 ------------------------- | ------------ | -------------------------- | ----- | ----
-1.5.0 (in development)    | n/a          | 2.0           | [branch develop_2.0](https://github.com/swagger-api/swagger-core/tree/develop_2.0) | [1.5 Milestone](https://github.com/swagger-api/swagger-core/milestones/v1.5)
-1.5.0-M1  | 2015-01-31          | 2.0           | [branch 1.5.0-M1](https://github.com/swagger-api/swagger-core/tree/1.5.0-M1) | JAX-RS support only
-1.3.12                     | 2014-12-23   | 1.2           | [tag v1.3.12](https://github.com/swagger-api/swagger-core/tree/v1.3.12)
+1.5.0-M2                  | 2015-03-30   | 2.0           | [master](https://github.com/swagger-api/swagger-core) |
+1.3.12                    | 2014-12-23   | 1.2           | [tag v1.3.12](https://github.com/swagger-api/swagger-core/tree/v1.3.12)
 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)
 1.0.0                     | 2011-10-16   | 1.0           | [tag v1.0](https://github.com/swagger-api/swagger-core/tree/v1.0)
 
 ## Overview
-This is a project to build the swagger-core library, which is required for the Reverb implementation of the Swagger spec. For more information about Wordnik's APIs, please visit http://developer.wordnik.com.
-
+This is a project to build the swagger-core library, which is required for the Reverb 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).
@@ -44,11 +42,13 @@ If you're interested in the change history of swagger and the swagger-core frame
 ### Prerequisites
 You need the following installed and available in your $PATH:
 
-<li>- Java 7 (http://java.oracle.com)
+<li>- Java 6 (http://java.oracle.com)
 
 <li>- Apache maven 3.0.4 or greater (http://maven.apache.org/)
 
-### To build from source (currently 1.3.12)
+<li>- Jackson 2.4.2 or greater
+
+### To build from source (currently 1.5.0-M2)
 ```
 # first time building locally
 mvn -N
@@ -66,36 +66,8 @@ Of course if you don't want to build locally you can grab artifacts from maven c
 `http://repo1.maven.org/maven2/com/wordnik/`
 
 ## Sample Apps
-There are a number of sample apps in the [samples](https://github.com/swagger-api/swagger-core/tree/master/samples) folder:
-
-[java-jaxrs](https://github.com/swagger-api/swagger-core/tree/master/samples/java-jaxrs/README.md) Java-based swagger server with JAX-RS
-
-[scala-jaxrs](https://github.com/swagger-api/swagger-core/tree/master/samples/scala-jaxrs/README.md) Scala-based swagger server with JAX-RS
-
-[scala-jaxrs-apm](https://github.com/swagger-api/swagger-core/tree/master/samples/scala-jaxrs-apm/README.md) 
-Scala-based swagger server using wordnik-oss utils for Application Performance Monitoring (APM)
-
-To run a sample app after initial compile:
-
-```
-# run scala-jaxrs sample app
-cd samples/scala-jaxrs
-
-mvn jetty:run
-```
-
-And the [Play2](http://playframework.org) samples:
-
-[java-play2](https://github.com/swagger-api/swagger-core/tree/master/samples/java-play2) Java-based Play2 sample app
-
-[scala-play2](https://github.com/swagger-api/swagger-core/tree/master/samples/scala-play2) Scala-based Play2 sample app
-
-To run the Play2 sample apps:
-
-```
-cd samples/java-play2
+There are a number of sample apps in the [samples](https://github.com/swagger-api/swagger-core/tree/develop_2.0/samples) folder.
 
-sbt run
 ```
 
 License

modules/swagger-annotations/pom.xml

@@ -2,20 +2,21 @@
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <parent>
     <groupId>com.wordnik</groupId>
-    <artifactId>swagger-project_2.10</artifactId>
-    <version>1.3.12</version>
+    <artifactId>swagger-project</artifactId>
+    <version>1.5.0-M2</version>
     <relativePath>../..</relativePath>
   </parent>
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.wordnik</groupId>
   <artifactId>swagger-annotations</artifactId>
-  <version>1.3.12</version>
+  <version>1.5.0-M2</version>
   <packaging>bundle</packaging>
   <name>swagger-annotations</name>
 
   <build>
     <sourceDirectory>src/main/java</sourceDirectory>
     <defaultGoal>install</defaultGoal>
+
     <plugins>
       <plugin>
         <groupId>org.apache.felix</groupId>
@@ -28,5 +29,6 @@
         </configuration>
       </plugin>
     </plugins>
+
   </build>
 </project>

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

@@ -1,5 +1,5 @@
 /**
- *  Copyright 2014 Reverb Technologies, Inc.
+ *  Copyright 2015 Reverb Technologies, Inc.
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -21,10 +21,10 @@
 
 /**
  * Marks a class as a Swagger resource.
- * <p/>
+ * <p>
  * The resource affects both the root document of Swagger, the Resource
  * Listing, and the API Declaration of that specific resource.
- * <p/>
+ * <p>
  * Swagger 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).
@@ -33,87 +33,120 @@
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
 public @interface Api {
-    /**
-     * The 'path' that is going to be used to host the API Declaration of the
-     * resource.
-     * <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.
-     * <p/>
-     * For Servlets, this path has to be the path serving the Servlet.
-     * <p/>
-     * If the value isn't preceded with a slash, one would be added to it.
-     */
-    String value();
+  /**
+   * The 'path' that is going to be used to host the API Declaration of the
+   * resource.
+   * <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.
+   * <p>
+   * For Servlets, this path has to be the path serving the Servlet.
+   * <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
+   */
+  String value() default "";
 
-    /**
-     * Corresponds to the `description` field of the Resource Listing API operation.
-     * <p/>
-     * This should be a short description of the resource.
-     */
-    String description() default "";
+  /**
+   * A list of tags for API documentation control. 
+   * Tags can be used for logical grouping of operations by resources or any other qualifier.
+   * 
+   * @since 1.5.2
+   *
+   * @return a string array of tag values
+   */
+  String[] tags() 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.
-     *
-     * @since 1.3.7
-     */
-    String basePath() default "";
+  /**
+   * Corresponds to the `description` field of the Resource Listing API operation.
+   * <p>
+   * This should be a short description of the resource.
+   *
+   * @return a longer description about this API
+   */
+  String description() default "";
 
-    /**
-     * Optional explicit ordering of this API resource in the Resource Listing.
-     */
-    int position() default 0;
+  /**
+   * 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
+   *
+   * @return the basePath for this operation
+   */
+  @Deprecated
+  String basePath() default "";
 
-    /**
-     * Corresponds to the `produces` field of the API Declaration.
-     * <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.
-     * <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.
-     */
-    String produces() default "";
+  /**
+   * Optional explicit ordering of this API resource in the Resource Listing.
+   * As of swagger-spec 2.0, this value is no longer used
+   *
+   *
+   * @return the position of this API in the resource listing
+   */
+  @Deprecated
+  int position() default 0;
 
-    /**
-     * Corresponds to the `consumes` field of the API Declaration.
-     * <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.
-     * <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
-     * for the Swagger documentation.
-     */
-    String consumes() default "";
+  /**
+   * Corresponds to the `produces` field of the API Declaration.
+   * <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.
+   * <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
+   */
+  String produces() default "";
 
-    /**
-     * This property is currently not in use.
-     */
-    String protocols() default "";
+  /**
+   * Corresponds to the `consumes` field of the API Declaration.
+   * <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.
+   * <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
+   * for the Swagger documentation.
+   * 
+   * @return the consumes value, or empty string if not set
+   */
+  String consumes() default "";
 
-    /**
-     * Corresponds to the `authorizations` field of the API Declaration.
-     * <p/>
-     * Takes in a list of the required authorizations for this API Resource.
-     * This may be overridden by specific operations.
-     *
-     * @see Authorization
-     */
-    Authorization[] authorizations() default @Authorization("");
+  /**
+   * This property is currently not in use.
+   * 
+   * @return the protocols supported by the server
+   */
+  String protocols() default "";
 
-    /**
-     * Hides the api.
-     *
-     * @since 1.3.8
-     */
-    boolean hidden() default false;
+  /**
+   * Corresponds to the `authorizations` field of the API Declaration.
+   * <p>
+   * Takes in a list of the required authorizations for this API 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
+   */
+  Authorization[] authorizations() default @Authorization(value = "", type = "");
+
+  /**
+   * Hides the api.
+   *
+   * @since 1.3.8
+   *
+   * @return true if the api should be hidden from the swagger documentation
+   */
+  boolean hidden() default false;
 }