updated annotations

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

@@ -23,36 +23,90 @@
 
 
 /**
- * describes a top-level api.  Classes with @Api annotations will
- * be included in the Resource Listing: https://github.com/wordnik/swagger-core/wiki/Resource-Listing
- * for details
+ * 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
+ * with {@code @Api} and will ignore other resources (JAX-RS endpoints, Servlets and
+ * so on).
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Api {
-  /** Short description of the Api */
-  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.
+     */
+    String value();
 
-  /** General description of this class */
-  String description() 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 "";
 
-  /** The base path that is prepended to all @Path elements. This may be an override for certain scenarios only */
-  String basePath() default "";
-
-  /** optional explicit ordering of this Api 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.
+     */
+    String basePath() default "";
 
-  /** content type produced by this Api */
-  String produces() default "";
+    /**
+     * Optional explicit ordering of this API resource in the Resource Listing.
+     */
+    int position() default 0;
 
-  /** media type consumed by this Api */
-  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.
+     */
+    String produces() default "";
 
-  /** protocols that this Api requires (i.e. https) */
-  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.
+     */
+    String consumes() default "";
 
-  /** authorizations required by this Api */
-  // String authorizations() default "";
-  /** authorizations required by this Api */
-  Authorization[] authorizations() default @Authorization("");
+    /**
+     * This property is currently not in use.
+     */
+    String protocols() 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("");
 }

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

@@ -22,41 +22,91 @@
 import java.lang.annotation.Target;
 
 /**
- * Represents a single parameter in an Api Operation.  A parameter is an input
- * to the operation.  The difference with the ApiImplicitParam is that they are
- * not bound to a variable, and allow for more manually-defined descriptions.
+ * Represents a single parameter in an API Operation.
+ * <p/>
+ * While {@link com.wordnik.swagger.annotations.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/>
+ * This annotation must be used as a value of {@link com.wordnik.swagger.annotations.ApiImplicitParams}
+ * in order to be parsed.
+ *
+ * @see com.wordnik.swagger.annotations.ApiImplicitParams
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ApiImplicitParam {
-  /** Name of the parameter */
-  String name() default "";
+    /**
+     * Name of the parameter.
+     * <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>
+     * <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>
+     *
+     * @see #paramType()
+     */
+    String name() default "";
 
-  /** Description of the parameter */
-  String value() default "";
+    /**
+     * A brief description of the parameter.
+     */
+    String value() default "";
 
-  /** Default value  - if e.g. no JAX-RS @DefaultValue is given */
-  String defaultValue() default "";
+    /**
+     * Describes the default value for the parameter.
+     */
+    String defaultValue() default "";
 
-  /** Description of values this endpoint accepts */
-  String allowableValues() default "";
+    /**
+     * 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 surrounded by square brackets.
+     * 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 "";
 
-  /** specifies if the parameter is required or not */
-  boolean required() default false;
+    /**
+     * Specifies if the parameter is required or not.
+     * <p/>
+     * Path parameters should always be set as required.
+     */
+    boolean required() default false;
 
-  /** 
-   * 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
-   */
-  String access() default "";
+    /**
+     * Allows for filtering a parameter from the API documentation.
+     *
+     * @see com.wordnik.swagger.core.filter.SwaggerSpecFilter
+     */
+    String access() default "";
 
-  /** specifies whether or not the parameter can have multiple values provided */
-  boolean allowMultiple() default false;
+    /**
+     * Specifies whether the parameter can accept multiple comma-separated values.
+     */
+    boolean allowMultiple() default false;
 
-  /** manually set the dataType */
-  String dataType() default "";
+    /**
+     * The data type of the parameter.
+     * <p/>
+     * This can be the class name or a primitive.
+     */
+    String dataType() default "";
 
-  /** manually set the param type, i.e. query, path, etc. */
-  String paramType() default "";
+    /**
+     * The parameter type of the parameter.
+     *
+     * Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}.
+     */
+    String paramType() default "";
 }

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

@@ -22,10 +22,15 @@
 import java.lang.annotation.Target;
 
 /**
- * A simple array wrapper to contain multiple ApiImplicitParam objects
+ * A wrapper to allow a list of multiple {@link com.wordnik.swagger.annotations.ApiImplicitParam} objects.
+ *
+ * @see com.wordnik.swagger.annotations.ApiImplicitParam
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ApiImplicitParams {
-  ApiImplicitParam[] value();
+    /**
+     * A list of {@link com.wordnik.swagger.annotations.ApiImplicitParam}s available to the API operation.
+     */
+    ApiImplicitParam[] value();
 }

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

@@ -22,26 +22,41 @@
 import java.lang.annotation.Target;
 
 /**
- * A bean class used in the REST-api.
- * Suppose you have an interface
- * <code>@PUT @ApiOperation(...) void foo(FooBean fooBean)</code>, there is
- * no direct way to see what fields <code>FooBean</code> would have. This
- * annotation is meant to give a description of <code>FooBean</code> and
- * then have the fields of it be annotated with
- * <code>@ApiModelProperty</code>.
- *
- * @author Heiko W. Rupp
+ * Provides additional information about Swagger models.
+ * <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.
  */
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ApiModel {
-  /** Provide a synopsis of this class */
-  String value() default "";
-  /** Provide a longer description of the class */
-  String description() default "";
-  /** Provide a superclass for the model to allow describing inheritence */
-  Class<?> parent() default Void.class;
-  /** for models with a base class, a discriminator can be provided for polymorphic use cases */
-  String discriminator() default "";
-  Class<?>[] subTypes() default {};
+    /**
+     * Provide an alternative name for the model.
+     * <p/>
+     * By default, the class name is used.
+     */
+    String value() default "";
+
+    /**
+     * Provide a longer description of the class.
+     */
+    String description() default "";
+
+    /**
+     * Provide a superclass for the model to allow describing inheritance.
+     */
+    Class<?> parent() default Void.class;
+
+    /**
+     * Supports model inheritance and polymorphism.
+     * <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.
+     */
+    String discriminator() default "";
+
+    /**
+     * An array of the sub types inheriting from this model.
+     */
+    Class<?>[] subTypes() default {};
 }