Skip to content

Commit

Permalink
reformatted for release
Browse files Browse the repository at this point in the history
  • Loading branch information
Ole Lensmar committed Aug 3, 2015
1 parent bb4c6fd commit 8d4e2cb
Show file tree
Hide file tree
Showing 80 changed files with 337 additions and 425 deletions.
29 changes: 13 additions & 16 deletions modules/swagger-annotations/src/main/java/io/swagger/annotations/Api.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -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.
Expand All @@ -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 "";

Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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 = "");

Expand Down
16 changes: 8 additions & 8 deletions modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiImplicitParam.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand All @@ -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>
Expand All @@ -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.
Expand All @@ -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 "";
Expand All @@ -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 "";
Expand Down
6 changes: 3 additions & 3 deletions modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiModel.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand All @@ -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 "";
Expand All @@ -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.
*/
Expand Down
4 changes: 2 additions & 2 deletions modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiModelProperty.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
*/
Expand Down
42 changes: 20 additions & 22 deletions modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiOperation.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand All @@ -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.
Expand All @@ -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 "";
Expand All @@ -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 "";
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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 = "");

Expand All @@ -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;
Expand Down
Loading

0 comments on commit 8d4e2cb

Please sign in to comment.