Showing 384 changed files with 10,157 additions and 1,678 deletions.
2 LICENSE
View file
@@ -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.
8 README.md
View file
@@ -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.
4 modules/swagger-annotations/pom.xml
View file
@@ -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>

83 modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/Api.java
View file
@@ -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
*/
11 ...s/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiImplicitParam.java
View file
@@ -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;

2 .../swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiImplicitParams.java
View file
@@ -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.
2 modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiModel.java
View file
@@ -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.
65 ...s/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiModelProperty.java
View file
@@ -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;
}