From dd567d6c12d520490836d8c4d04f16f91896cae8 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Sat, 12 Jul 2014 22:44:04 -0700 Subject: [PATCH] updated annotations --- .../com/wordnik/swagger/annotations/Api.java | 98 +++++++++--- .../swagger/annotations/ApiImplicitParam.java | 100 +++++++++--- .../annotations/ApiImplicitParams.java | 9 +- .../wordnik/swagger/annotations/ApiModel.java | 51 ++++--- .../swagger/annotations/ApiModelProperty.java | 93 +++++++----- .../swagger/annotations/ApiOperation.java | 143 +++++++++++++----- .../wordnik/swagger/annotations/ApiParam.java | 78 +++++++--- .../swagger/annotations/ApiResponse.java | 43 ++++-- .../swagger/annotations/ApiResponses.java | 12 +- .../swagger/annotations/Authorization.java | 27 +++- .../annotations/AuthorizationScope.java | 26 +++- 11 files changed, 500 insertions(+), 180 deletions(-) diff --git a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/Api.java b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/Api.java index 8467f709fd..c210d07dc6 100644 --- a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/Api.java +++ b/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. + *

+ * The resource affects both the root document of Swagger, the Resource + * Listing, and the API Declaration of that specific resource. + *

+ * 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. + *

+ * 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. + *

+ * For Servlets, this path has to be the path serving the Servlet. + *

+ * 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. + *

+ * 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. + *

+ * 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. + *

+ * 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 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. + *

+ * 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 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. + *

+ * 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(""); } diff --git a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiImplicitParam.java b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiImplicitParam.java index f0c9016ca7..a41b42ee06 100644 --- a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiImplicitParam.java +++ b/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. + *

+ * 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. + *

+ * 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. + *

+ * For proper Swagger functionality, follow these rules when naming your parameters based on {@link #paramType()}: + *

    + *
  1. If {@code paramType} is "path", the name should be the associated section in the path.
    2. + *
  2. If {@code paramType} is "body", the name should be "body".
    3. + *
  3. For all other cases, the name should be the parameter name as your application expects to accept.
    4. + *
+ * + * @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. + *

+ * There are three ways to describe the allowable values: + *

    + *
  1. To set a list of values, provide a comma-separated list surrounded by square brackets. + * For example: {@code [first, second, third]}.
    2. + *
  2. 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]}.
    3. + *
  3. 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.
    4. + *
+ */ + String allowableValues() default ""; - /** specifies if the parameter is required or not */ - boolean required() default false; + /** + * Specifies if the parameter is required or not. + *

+ * 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. + *

+ * 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 ""; } diff --git a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiImplicitParams.java b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiImplicitParams.java index 2d4b622a31..d992a36e50 100644 --- a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiImplicitParams.java +++ b/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(); } diff --git a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiModel.java b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiModel.java index e87f033003..078b2269b7 100644 --- a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiModel.java +++ b/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 - * @PUT @ApiOperation(...) void foo(FooBean fooBean), there is - * no direct way to see what fields FooBean would have. This - * annotation is meant to give a description of FooBean and - * then have the fields of it be annotated with - * @ApiModelProperty. - * - * @author Heiko W. Rupp + * Provides additional information about Swagger models. + *

+ * 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. + *

+ * 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. + *

+ * 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 {}; } diff --git a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiModelProperty.java b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiModelProperty.java index 6e30bb2a97..5368d95123 100644 --- a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiModelProperty.java +++ b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiModelProperty.java @@ -21,56 +21,65 @@ 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 */ - String value() default ""; + /** + * A brief description of this property. + */ + String value() default ""; + + /** + * Limits the acceptable values for this property. + *

+ * There are three ways to describe the allowable values: + *

    + *
  1. To set a list of values, provide a comma-separated list surrounded by square brackets. + * For example: {@code [first, second, third]}.
    2. + *
  2. 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]}.
    3. + *
  3. 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.
    4. + *
+ */ + String allowableValues() default ""; - /** - * If the values that can be set are restricted, they can be set here. In the form of a comma separated list - * registered, active, closed. - * - * @return the allowable values - */ - String allowableValues() default ""; + /** + * Allows for filtering a property from the API documentation. + * + * @see com.wordnik.swagger.core.filter.SwaggerSpecFilter + */ + String access() 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 - */ - String access() default ""; + /** + * Currently not in use. + */ + String notes() default ""; - /** long description of the property */ - String notes() default ""; + /** + * The data type of the parameter. + *

+ * 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 ""; - /** - * 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. - */ - String dataType() default ""; + /** + * Specifies if the parameter is required or not. + */ + boolean required() default false; - /** - * Whether or not the property is required, defaults to false. - * - * @return true if required, false otherwise - */ - boolean required() default false; + /** + * Allows explicitly ordering the property in the model. + */ + int position() default 0; - /** - * 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. - */ - int position() default 0; - - /** - * Allows a model property to be marked as hidden in the swagger model definition - */ - boolean hidden() default false; + /** + * Allows a model property to be hidden in the Swagger model definition. + */ + boolean hidden() default false; } diff --git a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiOperation.java b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiOperation.java index 99b94fe1d5..b17f57f80f 100644 --- a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiOperation.java +++ b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiOperation.java @@ -22,54 +22,129 @@ import java.lang.annotation.Target; /** - * Describes an operation or typically a HTTP method against a specific path. Operations - * with equivalent paths are grouped in an array in the Api Declaration. See - * https://github.com/wordnik/swagger-core/wiki/API-Declaration + * Describes an operation or typically a HTTP method against a specific path. + *

+ * Operations with equivalent paths are grouped in an array in the Api Declaration. + * A combination of a HTTP method and a path creates a unique operation. */ @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface ApiOperation { - /** Brief description of the operation */ - String value(); + /** + * Corresponds to the `summary` field of the operation. + *

+ * Provides a brief description of this operation. Should be 120 characters or less + * for proper visibility in Swagger-UI. + */ + String value(); - /** long description of the operation */ - String notes() default ""; + /** + * Corresponds to the 'notes' field of the operation. + *

+ * A verbose description of the operation. + */ + String notes() default ""; - /** default response class from the operation */ - Class response() default Void.class; + /** + * The response type of the operation. + *

+ * 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. + *

+ * Setting this property would override any automatically-derived data type. + *

+ * 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; - /** if the response class is within a container, specify it here */ - String responseContainer() default ""; + /** + * Notes whether the response type is a list of values. + *

+ * Valid values are "List", "Array" and "Set". "List" and "Array" are regular lists (no + * difference between them), and "Set" means the list contains unique values only. + *

+ * Any other value will be ignored. + */ + String responseContainer() default ""; - /** currently not implemented in readers, reserved for future use */ - String tags() default ""; + /** + * Currently not implemented in readers, reserved for future use. + */ + String tags() default ""; - /** the HTTP method, i.e GET, PUT, POST, DELETE, PATCH, OPTIONS */ - String httpMethod() default ""; + /** + * Corresponds to the `method` field as the HTTP method used. + *

+ * 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. + *

+ * For Servlets, you must specify the HTTP method manually. + *

+ * Acceptable values are "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH". + */ + String httpMethod() default ""; - /** allow explicit ordering of operations inside the Api Declaration */ - int position() default 0; + /** + * Optional explicit ordering of this API resource in the Resource Listing. + */ + int position() default 0; - /** the nickname for the operation, to override what is detected by the annotation scanner */ - String nickname() default ""; - - /** content type produced by this Api */ - String produces() default ""; + /** + * Corresponds to the `nickname` field. + *

+ * The nickname field is used by third-party tools to uniquely identify this operation. In JAX-RS environemnt, this + * would default to the method name, but can be overridden. + *

+ * For Servlets, you must specify this field. + */ + String nickname() default ""; - /** media type consumed by this Api */ - String consumes() default ""; + /** + * Corresponds to the `produces` field of the operation. + *

+ * 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 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 operation. + *

+ * 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 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 ""; + /** + * This property is currently not in use. + */ + String protocols() default ""; - /** authorizations required by this Api */ - Authorization[] authorizations() default @Authorization(""); + /** + * Corresponds to the `authorizations` field of the operation. + *

+ * Takes in a list of the required authorizations for this operation. + * + * @see Authorization + */ + Authorization[] authorizations() default @Authorization(""); - /** - * Allows an operation to be marked as hidden - */ - boolean hidden() default false; + /** + * Hides the operation from the list of operations. + */ + boolean hidden() default false; } diff --git a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiParam.java b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiParam.java index 0529f848f9..3d30a70919 100644 --- a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiParam.java +++ b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiParam.java @@ -22,34 +22,72 @@ import java.lang.annotation.Target; /** - * Represents a single parameter in an Api Operation. A parameter is an input - * to the operation + * Adds additional meta-data for operation parameters. + *

+ * This annotation can be used only in combination of JAX-RS 1.x/2.x annotations. */ @Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) public @interface ApiParam { - /** Name of the parameter */ - String name() default ""; + /** + * The parameter name. + *

+ * The name of the parameter will be derived from the field/method/parameter name, + * however you can override it. + *

+ * Body parameters will always be named "body". Path parameters will always be named + * as the path section they represent. + */ + 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. + *

+ * If the parameter is annotated with JAX-RS's {@code @DefaultValue}, that value would + * be used, but can be overridden by setting this property. + */ + String defaultValue() default ""; - /** Description of values this endpoint accepts */ - String allowableValues() default ""; + /** + * Limits the acceptable values for this parameter. + *

+ * If the original parameter type is an enum, the values of the enum would be translated to + * the allowableValues. Those can be overridden by setting this property. + *

+ * There are three ways to describe the allowable values: + *

    + *
  1. To set a list of values, provide a comma-separated list surrounded by square brackets. + * For example: {@code [first, second, third]}.
    2. + *
  2. 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]}.
    3. + *
  3. 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.
    4. + *
+ */ + String allowableValues() default ""; - /** specifies if the parameter is required or not */ - boolean required() default false; + /** + * Specifies if the parameter is required or not. + *

+ * Path parameters will always be set as required, whether you set this property or not. + */ + 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; } \ No newline at end of file diff --git a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiResponse.java b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiResponse.java index 91ba9b072f..151bef8dfe 100644 --- a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiResponse.java +++ b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiResponse.java @@ -23,21 +23,42 @@ /** - * An ApiResponse represents a type of response from a server. This can be used to - * describe both success codes as well as errors. - * If your Api has different response classes, you can describe them here by associating - * a response class with a response code. Note, Swagger does not allow multiple response - * types for a single response code. + * Describes a possible response of an operation. + *

+ * This can be used to describe possible success and error codes from your REST API call. + * You may or may not use this to describe the return type of the operation (normally a + * successful code), but the successful response should be described as well using the + * {@link ApiOperation}. + *

+ * If your API has uses a different response class for these responses, you can describe them + * here by associating a response class with a response code. + * Note, Swagger does not allow multiple response types for a single response code. + *

+ * This annotation is not used directly and will not be parsed by Swagger. It should be used + * within the {@link ApiResponses}. + * + * @see ApiOperation + * @see ApiResponses */ @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface ApiResponse { - /** Response code to describe */ - int code(); + /** + * The HTTP status code of the response. + *

+ * The value should be one of the formal HTTP Status Code Definitions. + */ + int code(); - /** Human-readable message to accompany the response */ - String message(); + /** + * Human-readable message to accompany the response. + */ + String message(); - /** Optional response class to describe the payload of the message */ - Class response() default Void.class; + /** + * Optional response class to describe the payload of the message. + *

+ * Corresponds to the `responseModel` field of the response message object. + */ + Class response() default Void.class; } diff --git a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiResponses.java b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiResponses.java index b3992c7eab..87da5dad21 100644 --- a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiResponses.java +++ b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiResponses.java @@ -22,10 +22,18 @@ import java.lang.annotation.Target; /** - * A simple array wrapper to contain multiple ApiResponse objects + * A wrapper to allow a list of multiple {@link com.wordnik.swagger.annotations.ApiResponse} objects. + *

+ * If you need to describe a single {@link com.wordnik.swagger.annotations.ApiResponse}, you still + * must use this annotation and wrap the {@code @ApiResponse} in an array. + * + * @see com.wordnik.swagger.annotations.ApiResponse */ @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface ApiResponses { - ApiResponse[] value(); + /** + * A list of {@link com.wordnik.swagger.annotations.ApiResponse}s provided by the API operation. + */ + ApiResponse[] value(); } diff --git a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/Authorization.java b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/Authorization.java index f1e6403839..bf23e5ee3a 100644 --- a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/Authorization.java +++ b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/Authorization.java @@ -21,9 +21,32 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Declares an authorization scheme to be used on a resource or an operation. + *

+ * The authorization scheme used needs to be defined in the Resource Listing's authorization + * section. + *

+ * This annotation is not used directly and will not be parsed by Swagger. It should be used + * within either {@link com.wordnik.swagger.annotations.Api} or {@link com.wordnik.swagger.annotations.ApiOperation}. + * + * @see com.wordnik.swagger.annotations.ApiOperation + * @see com.wordnik.swagger.annotations.Api + */ @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface Authorization { - String value(); - AuthorizationScope[] scopes() default @AuthorizationScope(scope = "", description = ""); + /** + * The name of the authorization scheme to be used on this resource/operation. + *

+ * The name must be defined in the Resource Listing's authorization section, + */ + String value(); + + /** + * The scopes to be used if the authorization scheme is OAuth2. + * + * @see com.wordnik.swagger.annotations.AuthorizationScope + */ + AuthorizationScope[] scopes() default @AuthorizationScope(scope = "", description = ""); } \ No newline at end of file diff --git a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/AuthorizationScope.java b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/AuthorizationScope.java index 335aecd292..0671873ab7 100644 --- a/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/AuthorizationScope.java +++ b/modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/AuthorizationScope.java @@ -21,9 +21,31 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Describes an OAuth2 authorization scope. + *

+ * Used to declare an authorization scope that is used by a resource or an operation for + * a defined authorization scheme. + *

+ * This annotation is not used directly and will not be parsed by Swagger. It should be used + * within the {@link com.wordnik.swagger.annotations.Authorization}. + * + * @see com.wordnik.swagger.annotations.Authorization + * @see com.wordnik.swagger.annotations.ApiOperation + * @see com.wordnik.swagger.annotations.Api + */ @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface AuthorizationScope { - String scope(); - String description(); + /** + * The scope of the OAuth2 Authorization scheme to be used. + *

+ * The scope should be previously defined in the Resource Listing's authorization section. + */ + String scope(); + + /** + * A brief description of the scope. + */ + String description(); }