Merge pull request #31 from turkeylurkey/updateJavadocs

Update the Javadocs for certain annotations

api/src/main/java/org/eclipse/microprofile/openapi/annotations/ExternalDocumentation.java

@@ -24,7 +24,15 @@
 import java.lang.annotation.Target;
 
 /**
- * Allows referencing an external resource for extended documentation.
+ * This annotation allows referencing an external resource for extended documentation.
+ * <p>
+ * When it is applied to a method the value of the annotation is added to the corresponding 
+ * OpenAPI operation definition.
+ * <p>
+ * When it is applied to a type and one or more of the fields are not empty strings the
+ * annotation value is added to the OpenAPI document root. If more than one non-empty 
+ * annotation is applied to a type in the application or if the externalDocs field of the 
+ * OpenAPIDefinition annotation is supplied the results are not defined. 
  **/
 @Target({ ElementType.METHOD, ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)

api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/ApiResponse.java

@@ -29,7 +29,23 @@
 import org.eclipse.microprofile.openapi.annotations.media.Content;
 
 /**
- * Describes a single response from an API Operation, including design-time, static links to operations based on the response.
+ * The ApiResponse annotation corresponds to the OpenAPI Response model object which 
+ * describes a single response from an API Operation, including design-time,
+ * static links to operations based on the response.
+ * <p>
+ * When this annotation is applied to a method the response is added to the responses
+ * defined in the corresponding OpenAPI operation. If the operation already has a 
+ * response with the specified responseCode the annotation on the method is ignored. 
+ * 
+ * <pre>
+ * &#64;ApiResponse(responseCode="200", description="Calculate load size", content=
+ *     [ &#64;Content(mediaType="application/json", Schema=&#64;Schema(type="integer")) ] )
+ * &#64;GET
+ * public getLuggageWeight(Flight id) {
+ *     return getBagWeight(id) + getCargoWeight(id);
+ * }
+ * </pre>
+ * 
  **/
 @Target({ ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)
@@ -55,7 +71,7 @@
      * <p>
      * RFC7230 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
      * 
-     * @return array of headers for this reponse instance
+     * @return array of headers for this response instance
      **/
     Header[] headers() default {};
 
@@ -67,7 +83,7 @@
     Link[] links() default {};
 
     /**
-     * An array containing descriptions of potential response payloads, for different media types.
+     * An array containing descriptions of potential response payloads for different media types.
      * 
      * @return content of this response instance
      **/

api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/ApiResponses.java

@@ -23,7 +23,10 @@
 import java.lang.annotation.Target;
 
 /**
- * This object represents an array of ApiResponse that can be specified for the operation.
+ * The ApiResponses annotation is a container for @ApiResponse annotations. When used on a method
+ * it is treated as if each ApiResponse annotation were applied individually.
+ * 
+ * @see ApiResponse
  **/
 @Target({ ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)

api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Server.java

@@ -25,24 +25,40 @@
 import java.lang.annotation.Target;
 
 /**
- * An object representing a Server.
+ * This annotation represents a Server used in an operation or used by all operations in an
+ * OpenAPI document. 
+ * <p>
+ * When a Server annotation appears on a method the server is added to the corresponding
+ * OpenAPI operation servers field.
+ * <p>
+ * When a Server annotation appears on a type then the server is added to all the operations 
+ * defined in that type except for those operations which already have one or more servers 
+ * defined. The server is also added to the servers defined in the root level of the 
+ * OpenAPI document. 
+ * <p>
+ * @see <a href=
+ * "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#server-object">
+ *      OpenAPI Specification Server Object</a>
  **/
 @Target({ ElementType.TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)
 @Repeatable(Servers.class)
 @Inherited
 public @interface Server {
     /**
-     * A URL to the target host. This URL supports Server Variables and may be relative, to indicate that the host location is relative to the
-     * location where the OpenAPI definition is being served. Variable substitutions will be made when a variable is named in {brackets}. This is a
-     * REQUIRED property.
+     * A URL to the target host. This URL supports Server Variables and may be
+     * relative, to indicate that the host location is relative to the location
+     * where the OpenAPI definition is being served. Variable substitutions will
+     * be made when a variable is named in {brackets}. This is a REQUIRED
+     * property.
      * 
      * @return URL to the target host
      **/
     String url() default "";
 
     /**
-     * An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+     * An optional string describing the host designated by the URL. CommonMark
+     * syntax MAY be used for rich text representation.
      * 
      * @return description of the host designated by URL
      **/

api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Servers.java

@@ -22,14 +22,23 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * 
+ * The Servers annotation is a container for @Server annotations. When used on a method or a type
+ * it is treated as if each server annotation were applied individually.
+ * 
+ * @see Server
+ *
+ */
 @Target({ ElementType.TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
 public @interface Servers {
     /**
-     * An array of Server Objects which is used to provide connectivity information to a target server.
+     * An array of Server objects which is used to provide connectivity
+     * information to a target server.
      *
-     * @return the servers used for this API
+     * @return the servers used for this API or endpoint.
      */
     Server[] value() default {};
 }

api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tag.java

@@ -27,7 +27,52 @@
 import org.eclipse.microprofile.openapi.annotations.ExternalDocumentation;
 
 /**
- * This object represents a tag. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#tagObject
+ * This object represents a tag. A tag is meta-information you can use to help
+ * organize your API endpoints and it can appear in two contexts.
+ * <p>
+ * Define tag objects on a method that implements an operation or on a type that
+ * contains operations. They will be gathered and stored in the root object of
+ * the OpenAPI document.
+ * <p>
+ * If the tag annotation is associated with a method that corresponds to an
+ * operation then the tag name will be added to the OpenAPI document and also be
+ * added to the operation tags (see @Operation).
+ * <p>
+ * If more than one tag is defined with the same name then only one tag with that name
+ * will appear in the OpenAPI document. 
+ * <p>
+ * If more than one tag is defined with the same name and only one tag contains a 
+ * description that is a non-empty string then that description will be preserved in 
+ * the OpenAPI document. If more than one non-empty description is specified the results 
+ * are implementation dependent. 
+ * <p>
+ * If more than one tag is defined with the same name and only one tag contains an
+ * external documentation that is defined with at least one non-empty string then that 
+ * external documentation will be preserved in the OpenAPI document. If more than one 
+ * non-empty external documentation is specified the results are implementation dependent. 
+ * <pre>
+ * &#64;Tag(name = "luggage", description = "Operations related to luggage handling.")
+ * &#64;GET
+ * public Location getLuggage(LuggageID id) {
+ *     return getLuggageLocation(id);
+ * }
+ * </pre>
+ * <p>
+ * If the tag annotation is applied to a type then the tag is defined in OpenAPI and a
+ * reference is added to each operation in the type.
+ * <p>
+ * Operations in your application can contain references to tag definitions to
+ * help organize the software. The @Operation annotation may contain a list of
+ * tag names.
+ * 
+ * <pre>
+ * &#64;Operation(summary = "Track luggage in the international division", 
+ *      tags = { "luggage", "international" }, ...
+ * </pre>
+ * 
+ * @see <a href=
+ *      "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#tagObject">
+ *      OpenAPI Specification Tag Object</a>
  */
 @Target({ ElementType.TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)

api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tags.java

@@ -23,14 +23,21 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * The Tags annotation is a container for @Tag annotations. When used on a method or a type
+ * it is treated as if each tag annotation were applied individually.
+ * 
+ * @see Tag
+ *
+ */
 @Target({ ElementType.TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
 public @interface Tags {
     /**
      * An array of Tag annotation objects which hold metadata for the API
      *
-     * @return rray of Tags
+     * @return an array of Tag annotations
      */
     Tag[] value() default {};
 }