Merge pull request #1316 from swagger-api/format-for-release

reformatted for release
swagger-api · Aug 3, 2015 · 91b29e0 · 91b29e0
2 parents bb4c6fd + 8d4e2cb
commit 91b29e0
Show file tree

Hide file tree

Showing 80 changed files with 337 additions and 425 deletions.
diff --git a/modules/swagger-annotations/src/main/java/io/swagger/annotations/Api.java b/modules/swagger-annotations/src/main/java/io/swagger/annotations/Api.java
@@ -22,10 +22,9 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-
 /**
  * Marks a class as a Swagger resource.
- * <p>
+ * <p/>
  * 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).
@@ -36,13 +35,13 @@
 public @interface Api {
     /**
      * Implicitly sets a tag for the operations, legacy support (read description).
-     * <p>
+     * <p/>
      * 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>
+     * <p/>
      * 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>
+     * <p/>
      * The leading / (if exists) will be removed.
      *
      * @return tag name for operations under this resource, unless {@link #tags()} is defined.
@@ -52,12 +51,11 @@
     /**
      * A list of tags for API documentation control.
      * Tags can be used for logical grouping of operations by resources or any other qualifier.
-     * <p>
+     * <p/>
      * A non-empty value will override the value provided in {@link #value()}.
      *
-     * @since 1.5.2-M1
-     *
      * @return a string array of tag values
+     * @since 1.5.2-M1
      */
     String[] tags() default "";
 
@@ -84,11 +82,11 @@
 
     /**
      * Corresponds to the `produces` field of the operations under this resource.
-     * <p>
+     * <p/>
      * Takes in comma-separated values of content types.
      * For example, "application/json, application/xml" would suggest the operations
      * generate JSON and XML output.
-     * <p>
+     * <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.
@@ -99,11 +97,11 @@
 
     /**
      * Corresponds to the `consumes` field of the operations under this resource.
-     * <p>
+     * <p/>
      * Takes in comma-separated values of content types.
      * For example, "application/json, application/xml" would suggest the operations
      * accept JSON and XML input.
-     * <p>
+     * <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.
@@ -114,7 +112,7 @@
 
     /**
      * Sets specific protocols (schemes) for the operations under this resource.
-     * <p>
+     * <p/>
      * Comma-separated values of the available protocols. Possible values: http, https, ws, wss.
      *
      * @return the protocols supported by the operations under the resource.
@@ -123,13 +121,12 @@
 
     /**
      * Corresponds to the `security` field of the Operation Object.
-     * <p>
+     * <p/>
      * 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.
+     * @see Authorization
      */
     Authorization[] authorizations() default @Authorization(value = "");
 

diff --git a/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiImplicitParam.java b/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiImplicitParam.java
@@ -23,12 +23,12 @@
 
 /**
  * Represents a single parameter in an API Operation.
- * <p>
+ * <p/>
  * While {@link ApiParam} is bound to a JAX-RS parameter,
  * method or field, this allows you to manually define a parameter in a fine-tuned manner.
  * This is the only way to define parameters when using Servlets or other non-JAX-RS
  * environments.
- * <p>
+ * <p/>
  * This annotation must be used as a value of {@link ApiImplicitParams}
  * in order to be parsed.
  *
@@ -39,7 +39,7 @@
 public @interface ApiImplicitParam {
     /**
      * Name of the parameter.
-     * <p>
+     * <p/>
      * 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>
@@ -62,7 +62,7 @@
 
     /**
      * Limits the acceptable values for this parameter.
-     * <p>
+     * <p/>
      * There are three ways to describe the allowable values:
      * <ol>
      * <li>To set a list of values, provide a comma-separated list.
@@ -79,14 +79,14 @@
 
     /**
      * Specifies if the parameter is required or not.
-     * <p>
+     * <p/>
      * Path parameters should always be set as required.
      */
     boolean required() default false;
 
     /**
      * Allows for filtering a parameter from the API documentation.
-     *<p>
+     * <p/>
      * See io.swagger.core.filter.SwaggerSpecFilter for further details.
      */
     String access() default "";
@@ -98,14 +98,14 @@
 
     /**
      * The data type of the parameter.
-     * <p>
+     * <p/>
      * This can be the class name or a primitive.
      */
     String dataType() default "";
 
     /**
      * The parameter type of the parameter.
-     *
+     * <p/>
      * Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}.
      */
     String paramType() default "";

diff --git a/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiModel.java b/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiModel.java
@@ -24,7 +24,7 @@
 
 /**
  * Provides additional information about Swagger models.
- * <p>
+ * <p/>
  * Classes will be introspected automatically as they are used as types in operations,
  * but you may want to manipulate the structure of the models.
  */
@@ -34,7 +34,7 @@
 public @interface ApiModel {
     /**
      * Provide an alternative name for the model.
-     * <p>
+     * <p/>
      * By default, the class name is used.
      */
     String value() default "";
@@ -51,7 +51,7 @@
 
     /**
      * Supports model inheritance and polymorphism.
-     * <p>
+     * <p/>
      * This is the name of the field used as a discriminator. Based on this field,
      * it would be possible to assert which sub type needs to be used.
      */

diff --git a/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiModelProperty.java b/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiModelProperty.java
@@ -41,7 +41,7 @@
 
     /**
      * Limits the acceptable values for this parameter.
-     * <p>
+     * <p/>
      * There are three ways to describe the allowable values:
      * <ol>
      * <li>To set a list of values, provide a comma-separated list.
@@ -68,7 +68,7 @@
 
     /**
      * The data type of the parameter.
-     * <p>
+     * <p/>
      * This can be the class name or a primitive. The value will override the data type as read from the class
      * property.
      */

diff --git a/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiOperation.java b/modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiOperation.java
@@ -23,7 +23,7 @@
 
 /**
  * Describes an operation or typically a HTTP method against a specific path.
- * <p>
+ * <p/>
  * Operations with equivalent paths are grouped in a single Operation Object.
  * A combination of a HTTP method and a path creates a unique operation.
  */
@@ -32,22 +32,22 @@
 public @interface ApiOperation {
     /**
      * Corresponds to the `summary` field of the operation.
-     * <p>
+     * <p/>
      * Provides a brief description of this operation. Should be 120 characters or less
      * for proper visibility in Swagger-UI.
      */
     String value();
 
     /**
      * Corresponds to the 'notes' field of the operation.
-     * <p>
+     * <p/>
      * A verbose description of the operation.
      */
     String notes() default "";
 
     /**
      * A list of tags for API documentation control.
-     * <p>
+     * <p/>
      * Tags can be used for logical grouping of operations by resources or any other qualifier.
      * A non-empty value will override the value received from {@link Api#value()} or {@link Api#tags()}
      * for this operation.
@@ -58,21 +58,21 @@
 
     /**
      * The response type of the operation.
-     * <p>
+     * <p/>
      * In JAX-RS applications, the return type of the method would automatically be used, unless it is
      * {@code javax.ws.rs.core.Response}. In that case, the operation return type would default to `void`
      * as the actual response type cannot be known.
-     * <p>
+     * <p/>
      * Setting this property would override any automatically-derived data type.
-     * <p>
+     * <p/>
      * If the value used is a class representing a primitive ({@code Integer}, {@code Long}, ...)
      * the corresponding primitive type will be used.
      */
     Class<?> response() default Void.class;
 
     /**
      * Declares a container wrapping the response.
-     * <p>
+     * <p/>
      * Valid values are "List", "Set" or "Map". Any other value will be ignored.
      */
     String responseContainer() default "";
@@ -86,14 +86,14 @@
 
     /**
      * Corresponds to the `method` field as the HTTP method used.
-     * <p>
+     * <p/>
      * If not stated, in JAX-RS applications, the following JAX-RS annotations would be scanned
      * and used: {@code @GET}, {@code @HEAD}, {@code @POST}, {@code @PUT}, {@code @DELETE} and {@code @OPTIONS}.
      * Note that even though not part of the JAX-RS specification, if you create and use the {@code @PATCH} annotation,
      * it will also be parsed and used. If the httpMethod property is set, it will override the JAX-RS annotation.
-     * <p>
+     * <p/>
      * For Servlets, you must specify the HTTP method manually.
-     * <p>
+     * <p/>
      * Acceptable values are "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH".
      */
     String httpMethod() default "";
@@ -105,19 +105,19 @@
 
     /**
      * Corresponds to the `operationId` field.
-     * <p>
+     * <p/>
      * The operationId is used by third-party tools to uniquely identify this operation. In Swagger 2.0, this is
      * no longer mandatory and if not provided will remain empty.
      */
     String nickname() default "";
 
     /**
      * Corresponds to the `produces` field of the operation.
-     * <p>
+     * <p/>
      * Takes in comma-separated values of content types.
      * For example, "application/json, application/xml" would suggest this operation
      * generates JSON and XML output.
-     * <p>
+     * <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.
@@ -126,11 +126,11 @@
 
     /**
      * Corresponds to the `consumes` field of the operation.
-     * <p>
+     * <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>
+     * <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.
@@ -139,22 +139,20 @@
 
     /**
      * Sets specific protocols (schemes) for this operation.
-     * <p>
+     * <p/>
      * Comma-separated values of the available protocols. Possible values: http, https, ws, wss.
      *
      * @return the protocols supported by the operations under the resource.
      */
     String protocols() default "";
 
-
     /**
      * Corresponds to the `security` field of the Operation Object.
-     * <p>
+     * <p/>
      * Takes in a list of the authorizations (security requirements) for this operation.
      *
-     * @see Authorization
-     *
      * @return an array of authorizations required by the server, or a single, empty authorization value if not set.
+     * @see Authorization
      */
     Authorization[] authorizations() default @Authorization(value = "");
 
@@ -172,7 +170,7 @@
 
     /**
      * The HTTP status code of the response.
-     * <p>
+     * <p/>
      * The value should be one of the formal <a target="_blank" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">HTTP Status Code Definitions</a>.
      */
     int code() default 200;