Merge pull request swagger-api#2541 from swagger-api/javadocs

improved annotations javadocs

Author: frantuma

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/ExternalDocumentation.java

@@ -23,7 +23,14 @@
 import java.lang.annotation.Target;
 
 /**
- * Allows referencing an external resource for extended documentation.
+ * The annotation may be used at method level or as field of {@link Operation} to add a reference to an external
+ * resource for extended documentation of an <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#operationObject">Operation (OpenAPI specification)</a>.
+ * <p>It may also be used to add external documentation to {@link io.swagger.v3.oas.annotations.tags.Tag},
+ * {@link io.swagger.v3.oas.annotations.headers.Header} or {@link io.swagger.v3.oas.annotations.media.Schema},
+ * or as field of {@link OpenAPIDefinition}.</p>
+ *
+ * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#externalDocumentationObject">External Documentation (OpenAPI specification)</a>
+ * @see OpenAPIDefinition
  **/
 @Target({ElementType.METHOD, ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/OpenAPIDefinition.java

@@ -27,6 +27,12 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * The annotation that may be used to populate OpenAPI Object fields info, tags, servers, security and externalDocs
+ * If more than one class is annotated with {@link OpenAPIDefinition}, with the same fields defined, behaviour is inconsistent.
+ *
+ * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#oasObject">OpenAPI (OpenAPI specification)</a>
+ */
 @Target({ElementType.TYPE, ElementType.PACKAGE})
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/Operation.java

@@ -28,7 +28,30 @@
 import java.lang.annotation.Target;
 
 /**
- * Describes a single API operation on a path.
+ * The annotation may be used to define a resource method as an OpenAPI Operation, and/or to define additional
+ * properties for the Operation.
+ *
+ * <p>Note: swagger-jaxrs2 reader engine includes by default also methods of scanned resources which are not annotated
+ * with @Operation, as long as a jax-rs @Path is defined at class and/or method level, together with the http method
+ * annotation (@GET, @POST, etc).</p>
+ * <p>This behaviour is controlled by configuration property `scanAllResources` which defaults to true. By setting this
+ * flag to false only @{@link Operation} annotated methods are considered.</p>
+ *
+ * <p>The following fields can also alternatively be defined at method level (as repeatable annotations in case of arrays),
+ * in this case method level annotations take precedence over @{@link Operation} annotation fields:</p>
+ *
+ * <ul>
+ * <li>tags: @{@link io.swagger.v3.oas.annotations.tags.Tag}</li>
+ * <li>externalDocs: @{@link ExternalDocumentation}</li>
+ * <li>parameters: @{@link Parameter}</li>
+ * <li>responses: @{@link ApiResponse}</li>
+ * <li>security: @{@link SecurityRequirement}</li>
+ * <li>servers: @{@link Server}</li>
+ * <li>extensions: @{@link Extension}</li>
+ * <li>hidden: @{@link Hidden}</li>
+ * </ul>
+ *
+ * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#operationObject">Operation (OpenAPI specification)</a>
  **/
 @Target({ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/Parameter.java

@@ -32,7 +32,19 @@
 import java.lang.annotation.Target;
 
 /**
- * Describes a single operation parameter
+ * The annotation may be used on a method parameter to define it as a parameter for the operation, and/or to define
+ * additional properties for the Parameter. It can also be used independently in {@link Operation#parameters()} or at
+ * method level to add a parameter to the operation, even if not bound to any method parameter.
+ *
+ * <p>swagger-jaxrs2 reader engine considers this annotation along with JAX-RS annotations, parameter type and context
+ * as input to resolve a method parameter into an OpenAPI Operation parameter.</p>
+ *
+ * <p>For method parameters bound to the request body, see {@link io.swagger.v3.oas.annotations.parameters.RequestBody}</p>
+ *
+ * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#parameterObject">Parameter (OpenAPI specification)</a>
+ * @see io.swagger.v3.oas.annotations.parameters.RequestBody
+ * @see Operation
+ * @see Schema
  **/
 @Target({ElementType.PARAMETER,
         ElementType.METHOD,

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/Parameters.java

@@ -21,6 +21,11 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Container for repeatable {@link Parameter} annotation
+ *
+ * @see Parameter
+ */
 @Target({ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/callbacks/Callback.java

@@ -26,7 +26,9 @@
 import java.lang.annotation.Target;
 
 /**
- * This object represents a callback URL that will be invoked.
+ * The annotation may be used at method level to add one ore more callbacks to the operation definition.
+ *
+ * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#callbackObject">Callback (OpenAPI specification)</a>
  **/
 @Target({ElementType.FIELD,
         ElementType.METHOD,

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/callbacks/Callbacks.java

@@ -23,8 +23,10 @@
 import java.lang.annotation.Target;
 
 /**
- * This object represents an array of Callback URLs that can be invoked.
- **/
+ * Container for repeatable {@link Callback} annotation
+ *
+ * @see Callback
+ */
 @Target({ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/extensions/Extension.java

@@ -8,6 +8,8 @@
 
 /**
  * An optionally named list of extension properties.
+ *
+ * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#specificationExtensions">Specification extensions (OpenAPI specification)</a>
  */
 @Target({ElementType.FIELD,
         ElementType.METHOD,

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/extensions/Extensions.java

@@ -23,8 +23,10 @@
 import java.lang.annotation.Target;
 
 /**
- * This object represents an array of extensions that can be added to the element.
- **/
+ * Container for repeatable {@link Extension} annotation
+ *
+ * @see Extension
+ */
 @Target({ElementType.FIELD,
         ElementType.METHOD,
         ElementType.PARAMETER,

modules/swagger-annotations/src/main/java/io/swagger/v3/oas/annotations/headers/Header.java

@@ -24,7 +24,14 @@
 import java.lang.annotation.Target;
 
 /**
- * Describes a single header object
+ * The annotation may be used to add one or more headers to the definition of a response or as attribute of content
+ * encoding by definining it as field {@link io.swagger.v3.oas.annotations.responses.ApiResponse#headers()} or {@link io.swagger.v3.oas.annotations.media.Content#encoding()}.
+ * <p>Please note that request headers are defined as Header {@link io.swagger.v3.oas.annotations.Parameter}.</p>
+ *
+ * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#headerObject">Header (OpenAPI specification)</a>
+ * @see io.swagger.v3.oas.annotations.responses.ApiResponse
+ * @see io.swagger.v3.oas.annotations.Parameter
+ * @see io.swagger.v3.oas.annotations.media.Encoding
  **/
 @Target({})
 @Retention(RetentionPolicy.RUNTIME)