From bbf134ade40106e40b0b72fe50d75510e4d6c1e7 Mon Sep 17 00:00:00 2001 From: Paul Gooderham Date: Wed, 15 Nov 2017 13:36:56 -0500 Subject: [PATCH] Update the Javadocs for certain annotations Tag, Tags, Server, Servers, ServerVariable, ApiResponse, ApiResponses, ExternalDocumentation. Issue #3 Signed-off-by: Paul Gooderham --- .../annotations/ExternalDocumentation.java | 10 +++- .../annotations/responses/ApiResponse.java | 22 +++++++-- .../annotations/responses/ApiResponses.java | 5 +- .../openapi/annotations/servers/Server.java | 26 ++++++++-- .../openapi/annotations/servers/Servers.java | 13 ++++- .../openapi/annotations/tags/Tag.java | 47 ++++++++++++++++++- .../openapi/annotations/tags/Tags.java | 9 +++- 7 files changed, 118 insertions(+), 14 deletions(-) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/ExternalDocumentation.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/ExternalDocumentation.java index afa6d3684..236e6d899 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/ExternalDocumentation.java +++ b/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. + *

+ * When it is applied to a method the value of the annotation is added to the corresponding + * OpenAPI operation definition. + *

+ * 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) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/ApiResponse.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/ApiResponse.java index fff23ca37..9551237e5 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/ApiResponse.java +++ b/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. + *

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

+ * @ApiResponse(responseCode="200", description="Calculate load size", content=
+ *     [ @Content(mediaType="application/json", Schema=@Schema(type="integer")) ] )
+ * @GET
+ * public getLuggageWeight(Flight id) {
+ *     return getBagWeight(id) + getCargoWeight(id);
+ * }
+ *
+ * **/ @Target({ ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @@ -55,7 +71,7 @@ *

* 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 **/ diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/ApiResponses.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/ApiResponses.java index 8a96decf2..d93bf15da 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/ApiResponses.java +++ b/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) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Server.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Server.java index 3ddc7129b..10e878727 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Server.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Server.java @@ -25,7 +25,20 @@ 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. + *

+ * When a Server annotation appears on a method the server is added to the corresponding + * OpenAPI operation servers field. + *

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

+ * @see + * OpenAPI Specification Server Object **/ @Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @@ -33,16 +46,19 @@ @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 **/ diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Servers.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Servers.java index dafac7fdb..b765a9c5e 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Servers.java +++ b/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 {}; } diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tag.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tag.java index f84a2b288..cf6d091d2 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tag.java +++ b/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. + *

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

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

+ * If more than one tag is defined with the same name then only one tag with that name + * will appear in the OpenAPI document. + *

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

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

+ * @Tag(name = "luggage", description = "Operations related to luggage handling.")
+ * @GET
+ * public Location getLuggage(LuggageID id) {
+ *     return getLuggageLocation(id);
+ * }
+ *
+ *

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

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

+ * @Operation(summary = "Track luggage in the international division", 
+ *      tags = { "luggage", "international" }, ...
+ *
+ * + * @see + * OpenAPI Specification Tag Object */ @Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tags.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tags.java index d1a3e236b..fba79086f 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tags.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tags.java @@ -23,6 +23,13 @@ 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 @@ -30,7 +37,7 @@ /** * 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 {}; }