From a0068d1913efc0d0cff17a62e5482c31424db33d Mon Sep 17 00:00:00 2001 From: Benjamin Confino Date: Thu, 2 May 2024 09:55:56 +0100 Subject: [PATCH] update version number in spec and references to spec --- README.adoc | 2 +- .../openapi/annotations/Components.java | 4 +- .../annotations/ExternalDocumentation.java | 5 +- .../annotations/OpenAPIDefinition.java | 3 +- .../openapi/annotations/Operation.java | 3 +- .../annotations/callbacks/Callback.java | 3 +- .../callbacks/CallbackOperation.java | 3 +- .../annotations/callbacks/Callbacks.java | 3 +- .../openapi/annotations/headers/Header.java | 3 +- .../openapi/annotations/info/Contact.java | 2 +- .../openapi/annotations/info/Info.java | 2 +- .../openapi/annotations/info/License.java | 2 +- .../openapi/annotations/links/Link.java | 3 +- .../openapi/annotations/media/Content.java | 4 +- .../media/DiscriminatorMapping.java | 5 +- .../openapi/annotations/media/Encoding.java | 3 +- .../annotations/media/ExampleObject.java | 3 +- .../openapi/annotations/media/Schema.java | 3 +- .../annotations/media/SchemaProperty.java | 3 +- .../annotations/parameters/Parameter.java | 3 +- .../annotations/parameters/Parameters.java | 3 +- .../annotations/parameters/RequestBody.java | 3 +- .../parameters/RequestBodySchema.java | 4 +- .../annotations/responses/APIResponse.java | 2 +- .../responses/APIResponseSchema.java | 2 +- .../annotations/responses/APIResponses.java | 3 +- .../annotations/security/OAuthFlow.java | 2 +- .../annotations/security/OAuthFlows.java | 2 +- .../annotations/security/OAuthScope.java | 2 +- .../security/SecurityRequirement.java | 5 +- .../security/SecurityRequirements.java | 5 +- .../security/SecurityRequirementsSet.java | 5 +- .../security/SecurityRequirementsSets.java | 5 +- .../annotations/security/SecurityScheme.java | 3 +- .../annotations/security/SecuritySchemes.java | 3 +- .../openapi/annotations/servers/Server.java | 3 +- .../annotations/servers/ServerVariable.java | 5 +- .../openapi/annotations/servers/Servers.java | 3 +- .../openapi/annotations/tags/Tag.java | 3 +- .../openapi/annotations/tags/Tags.java | 3 +- .../openapi/models/Components.java | 4 +- .../openapi/models/ExternalDocumentation.java | 5 +- .../microprofile/openapi/models/OpenAPI.java | 3 +- .../openapi/models/Operation.java | 3 +- .../microprofile/openapi/models/PathItem.java | 10 +- .../microprofile/openapi/models/Paths.java | 6 +- .../openapi/models/callbacks/Callback.java | 3 +- .../openapi/models/examples/Example.java | 3 +- .../openapi/models/headers/Header.java | 3 +- .../openapi/models/info/Contact.java | 2 +- .../openapi/models/info/Info.java | 2 +- .../openapi/models/info/License.java | 2 +- .../openapi/models/links/Link.java | 3 +- .../openapi/models/media/Discriminator.java | 5 +- .../openapi/models/media/Encoding.java | 5 +- .../openapi/models/media/MediaType.java | 4 +- .../openapi/models/media/Schema.java | 3 +- .../openapi/models/media/XML.java | 4 +- .../openapi/models/parameters/Parameter.java | 3 +- .../models/parameters/RequestBody.java | 5 +- .../openapi/models/responses/APIResponse.java | 2 +- .../models/responses/APIResponses.java | 5 +- .../openapi/models/security/OAuthFlow.java | 4 +- .../openapi/models/security/OAuthFlows.java | 2 +- .../models/security/SecurityRequirement.java | 5 +- .../models/security/SecurityScheme.java | 3 +- .../openapi/models/servers/Server.java | 5 +- .../models/servers/ServerVariable.java | 7 +- .../microprofile/openapi/models/tags/Tag.java | 3 +- .../microprofile/openapi/package-info.java | 4 +- .../microprofile-openapi-spec.asciidoc | 120 +++++++++--------- 71 files changed, 162 insertions(+), 204 deletions(-) diff --git a/README.adoc b/README.adoc index 5333be491..572020477 100644 --- a/README.adoc +++ b/README.adoc @@ -21,7 +21,7 @@ image:https://github.com/eclipse/microprofile-open-api/workflows/Build/badge.svg?branch=master[link=https://github.com/eclipse/microprofile-open-api/actions] -This MicroProfile specification aims at providing a unified Java API for the link:++https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md++[OpenAPI v3 specification], +This MicroProfile specification aims at providing a unified Java API for the link:++https://spec.openapis.org/oas/v3.1.0.html++[OpenAPI v3.1 specification], that all application developers can use to expose their API documentation. * The link:++https://github.com/eclipse/microprofile-open-api/tree/master/api/src/main/java/org/eclipse/microprofile/openapi++[spec APIs] are composed of annotations, models, and programming interfaces. diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Components.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Components.java index a3f9ae0ec..abb1d56c8 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Components.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Components.java @@ -36,8 +36,8 @@ * Describes the Components object that holds various reusable objects for different aspects of the OpenAPI * Specification (OAS). * - * @see OpenAPI - * Specification Components Object + * @see OpenAPI Specification Components + * Object */ @Target({}) @Retention(RetentionPolicy.RUNTIME) 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 7a8336495..8e115a974 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 @@ -35,9 +35,8 @@ * 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. * - * @see OpenAPI - * Specification External Documentation Object + * @see OpenAPI Specification + * External Documentation Object **/ @Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/OpenAPIDefinition.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/OpenAPIDefinition.java index 345c979bb..2459313f1 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/OpenAPIDefinition.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/OpenAPIDefinition.java @@ -35,8 +35,7 @@ *

* This is the root document object of the OpenAPI document. It contains required and optional fields. * - * @see OpenAPI - * Specification OpenAPI Object + * @see OpenAPI Specification OpenAPI Object */ @Target({ElementType.TYPE, ElementType.PACKAGE}) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Operation.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Operation.java index e587bd0f9..28b496d04 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Operation.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Operation.java @@ -28,8 +28,7 @@ /** * Describes a single API operation on a path. * - * @see OpenAPI - * Specification Operation Object + * @see OpenAPI Specification Operation Object **/ @Target({ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callback.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callback.java index 26064b76d..46a3bb2b5 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callback.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callback.java @@ -29,8 +29,7 @@ /** * This object represents a callback URL that will be invoked. * - * @see OpenAPI - * Specification Callback Object + * @see OpenAPI Specification Callback Object **/ @Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/CallbackOperation.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/CallbackOperation.java index 41cdf5339..29c85d531 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/CallbackOperation.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/CallbackOperation.java @@ -33,8 +33,7 @@ /** * Describes a single API callback operation. * - * @see OpenAPI - * Specification Operation Object + * @see OpenAPI Specification Operation Object **/ @Target({}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callbacks.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callbacks.java index c41e93a11..dc18f9cd2 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callbacks.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callbacks.java @@ -26,8 +26,7 @@ /** * This object represents an array of Callback URLs that can be invoked. * - * @see OpenAPI - * Specification Callback Object + * @see OpenAPI Specification Callback Object **/ @Target({ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/headers/Header.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/headers/Header.java index 97cb031ad..e14a5e8fa 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/headers/Header.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/headers/Header.java @@ -28,8 +28,7 @@ /** * Describes a single header object * - * @see OpenAPI - * Specification Header Object + * @see OpenAPI Specification Header Object **/ @Target({}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Contact.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Contact.java index 4e59d6c1b..483bb1741 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Contact.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Contact.java @@ -27,7 +27,7 @@ /** * Contact information for the exposed API. * - * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#contactObject" + * @see OpenAPI Specification Contact Object **/ @Target({}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Info.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Info.java index 5473efa24..9fa09ed8a 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Info.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Info.java @@ -27,7 +27,7 @@ /** * This annotation provides metadata about the API, and maps to the Info object in OpenAPI Specification 3. * - * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#infoObject" + * @see OpenAPI Specification Info Object **/ @Target({}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/License.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/License.java index 99c3f5617..a566daf20 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/License.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/License.java @@ -27,7 +27,7 @@ /** * License information for the exposed API. * - * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#licenseObject" + * @see OpenAPI Specification License Object **/ @Target({}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/links/Link.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/links/Link.java index 456bf55ab..b46fef51c 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/links/Link.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/links/Link.java @@ -30,8 +30,7 @@ * caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between * responses and other operations. * - * @see OpenAPI - * Specification Link Object + * @see OpenAPI Specification Link Object **/ @Target({}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Content.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Content.java index 7d09b708a..776c89e29 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Content.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Content.java @@ -27,8 +27,8 @@ /** * This object provides schema and examples for a particular media type. * - * @see OpenAPI - * Specification Media Type Object + * @see OpenAPI Specification Media Type + * Object **/ @Target({}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DiscriminatorMapping.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DiscriminatorMapping.java index 749fc5ebd..9f9ed8444 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DiscriminatorMapping.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DiscriminatorMapping.java @@ -25,9 +25,8 @@ /** * This object maps payload values to a particular Schema. * - * @see OpenAPI - * Specification Discriminator Object + * @see OpenAPI Specification Discriminator + * Object **/ @Target({}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Encoding.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Encoding.java index 036e3ce57..7d5dd78dd 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Encoding.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Encoding.java @@ -28,8 +28,7 @@ /** * Single encoding definition to be applied to single Schema Object * - * @see Encoding - * Object + * @see OpenAPI Specification Encoding Object **/ @Target({}) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/ExampleObject.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/ExampleObject.java index fda821c9d..1dd530ed3 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/ExampleObject.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/ExampleObject.java @@ -27,8 +27,7 @@ /** * This object illustrates an example of a particular content * - * @see OpenAPI - * Specification Example Object + * @see OpenAPI Specification Example Object **/ @Target({}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Schema.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Schema.java index d55335856..109d903c4 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Schema.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Schema.java @@ -31,8 +31,7 @@ * The Schema Object allows the definition of input and output data types. These types can be objects, but also * primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00. * - * @see OpenAPI - * Specification Schema Object + * @see OpenAPI Specification Schema Object **/ @Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/SchemaProperty.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/SchemaProperty.java index e603b2bcc..62b72c16e 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/SchemaProperty.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/SchemaProperty.java @@ -31,8 +31,7 @@ * * This object is an extended subset of the JSON Schema Specification Wright Draft 00. * - * @see OpenAPI - * Specification Schema Object + * @see OpenAPI Specification Schema Object * * @since 2.0 **/ diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameter.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameter.java index 6ea8f5176..634e0af5d 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameter.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameter.java @@ -35,8 +35,7 @@ /** * Describes a single operation parameter * - * @see OpenAPI - * Specification Parameter Object + * @see OpenAPI Specification Parameter Object **/ @Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameters.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameters.java index e41d0d703..d06cddf33 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameters.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameters.java @@ -26,8 +26,7 @@ /** * This object encapsulates input parameters * - * @see OpenAPI - * Specification Parameter Object + * @see OpenAPI Specification Parameter Object */ @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.METHOD}) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBody.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBody.java index c04ed72e9..0f07d8323 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBody.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBody.java @@ -29,8 +29,7 @@ /** * Describes a single request body. * - * @see requestBody + * @see OpenAPI Specification Request Body * Object **/ @Target({ElementType.PARAMETER, ElementType.METHOD}) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBodySchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBodySchema.java index 1bcea852e..ffeeb4fca 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBodySchema.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBodySchema.java @@ -58,8 +58,8 @@ * * * @see RequestBody - * @see OpenAPI - * requestBody Object + * @see OpenAPI Specification Request Body + * Object **/ @Target({ElementType.PARAMETER, ElementType.METHOD}) @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 6f6660362..87cbb8172 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 @@ -69,7 +69,7 @@ * } * * - * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#responseObject" + * @see OpenAPI Specification Response Object * **/ @Target({ElementType.METHOD, ElementType.TYPE}) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponseSchema.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponseSchema.java index 0a2f56426..a968d26eb 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponseSchema.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponseSchema.java @@ -58,7 +58,7 @@ * * @since 2.0 * @see APIResponse - * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#responseObject" + * @see OpenAPI Specification Response Object * **/ @Target({ElementType.METHOD}) 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 31dde7ef9..da5193592 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 @@ -28,8 +28,7 @@ * 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 Responses - * Object + * @see OpenAPI Specification Responses Object **/ @Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthFlow.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthFlow.java index c2c0cdc89..10ab24075 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthFlow.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthFlow.java @@ -27,7 +27,7 @@ /** * Configuration details for a supported OAuth Flow. * - * @see OAuth Flow + * @see OpenAPI Specification OAuth Flow * Object **/ @Target({}) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthFlows.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthFlows.java index 6c6907b45..593ce3fb7 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthFlows.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthFlows.java @@ -27,7 +27,7 @@ /** * Allows configuration of the supported OAuth Flows. * - * @see OAuthFlows + * @see OpenAPI Specification OAuth Flows * Object **/ @Target({}) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthScope.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthScope.java index 42833aea1..033430080 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthScope.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthScope.java @@ -25,7 +25,7 @@ /** * Represents an OAuth scope. * - * @see OAuthFlow + * @see OpenAPI Specification OAuth Flow * Object **/ @Target({}) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirement.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirement.java index 78e371219..62bd8f8e6 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirement.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirement.java @@ -30,9 +30,8 @@ * Applying this annotation to a method or class is equivalent to applying a {@link SecurityRequirementsSet} annotation * containing only this annotation. * - * @see SecuirtyRequirement - * Object + * @see OpenAPI Specification Security + * Requirement Object **/ @Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirements.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirements.java index d0a8b803b..0fe8fb5fa 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirements.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirements.java @@ -35,9 +35,8 @@ * - api_secret: [] * * - * @see SecurityRequirement - * Object + * @see OpenAPI Specification Security + * Requirement Object **/ @Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirementsSet.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirementsSet.java index db420077d..3bd85b215 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirementsSet.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirementsSet.java @@ -53,9 +53,8 @@ * oauth_implicit: [] * * - * @see SecurityRequirement - * Object + * @see OpenAPI Specification Security + * Requirement Object **/ @Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirementsSets.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirementsSets.java index 1d8b4a6e3..4ca0cdcd8 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirementsSets.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirementsSets.java @@ -49,9 +49,8 @@ * - api_secret: [] * * - * @see SecurityRequirement - * Object + * @see OpenAPI Specification Security + * Requirement Object **/ @Retention(RUNTIME) @Target({TYPE, METHOD}) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityScheme.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityScheme.java index 1610cb297..5155f1343 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityScheme.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityScheme.java @@ -33,7 +33,8 @@ * (either as a header or as a query parameter), OAuth2's common flows (implicit, password, application and access code) * as defined in RFC6749, and OpenID Connect Discovery. * - * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#security-scheme-object" + * @see OpenAPI Specification Security Scheme + * Object **/ @Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecuritySchemes.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecuritySchemes.java index f61c69ec9..e0064b6b8 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecuritySchemes.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecuritySchemes.java @@ -25,7 +25,8 @@ /** * This object represents an array of SecurityScheme annotations that can be specified at the definition level. * - * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#security-scheme-object" + * @see OpenAPI Specification Security Scheme + * Object **/ @Target({ElementType.TYPE}) @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 eaffd8fec..74163d34b 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 @@ -42,8 +42,7 @@ * {@link org.eclipse.microprofile.openapi.annotations.servers.Servers Servers} annotation are specified on the same * type, the server definitions will be combined. * - * @see OpenAPI - * Specification Server Object + * @see OpenAPI Specification Server Object **/ @Target({ElementType.TYPE, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/ServerVariable.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/ServerVariable.java index ef157eeb4..0417f3728 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/ServerVariable.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/ServerVariable.java @@ -27,9 +27,8 @@ /** * An object representing a Server Variable for server URL template substitution. * - * @see ServerVariable - * Object + * @see OpenAPI Specification Server + * Variable Object **/ @Target({}) @Retention(RetentionPolicy.RUNTIME) 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 118893605..8e5526cad 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 @@ -31,8 +31,7 @@ * {@link org.eclipse.microprofile.openapi.annotations.servers.Servers Servers} annotation are specified on the same * type, the server definitions will be combined. * - * @see Server - * Object + * @see OpenAPI Specification Server Object * */ @Target({ElementType.TYPE, ElementType.METHOD}) 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 c17fd6acb..34f8fceeb 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 @@ -68,8 +68,7 @@ * } * * - * @see OpenAPI - * Specification Tag Object + * @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 3c05eecdc..9a85ad1e6 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 @@ -31,8 +31,7 @@ * {@link org.eclipse.microprofile.openapi.annotations.tags.Tags Tags} annotations are specified on the same * method/class, then both tag definitions should be applied to method/class. * - * @see OpenAPI - * Specification Tag Object + * @see OpenAPI Specification Tag Object * */ @Target({ElementType.TYPE, ElementType.METHOD}) diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/Components.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/Components.java index f68310eaf..174af0d42 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/Components.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Components.java @@ -47,8 +47,8 @@ *

  • my.org.User
    • * * - * @see OpenAPI - * Specification Components Object + * @see OpenAPI Specification Components + * Object */ public interface Components extends Constructible, Extensible { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java index 1022bf59e..dc3c0a13e 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/ExternalDocumentation.java @@ -23,9 +23,8 @@ * Allows referencing an external resource for extended documentation. *

    * - * @see OpenAPI - * Specification External Documentation Object + * @see OpenAPI Specification + * External Documentation Object */ public interface ExternalDocumentation extends Constructible, Extensible { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java index 3433674ee..23ab72a3a 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/OpenAPI.java @@ -29,8 +29,7 @@ *

    * This is the root document object of the OpenAPI document. It contains required and optional fields. * - * @see OpenAPI - * Specification OpenAPI Object + * @see OpenAPI Specification OpenAPI Object */ public interface OpenAPI extends Constructible, Extensible { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/Operation.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/Operation.java index b1bedad49..48b431c83 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/Operation.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Operation.java @@ -33,8 +33,7 @@ * Describes a single API operation on a path. *

    * - * @see OpenAPI - * Specification Operation Object + * @see OpenAPI Specification Operation Object */ public interface Operation extends Constructible, Extensible { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java index e611e438b..e28389294 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/PathItem.java @@ -27,13 +27,13 @@ * PathItem *

    * Describes the operations available on a single path. A Path Item MAY be empty, due to - * security - * constraints. In that case the path itself is still exposed to the documentation viewer but you will not know - * which operations and parameters are available. + * security constraints. In that case the + * path itself is still exposed to the documentation viewer but you will not know which operations and parameters are + * available. *

    * - * @see OpenAPI - * Specification Path Item Object + * @see OpenAPI Specification Path Item + * Object */ public interface PathItem extends Constructible, Extensible, Reference { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/Paths.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/Paths.java index 100a644e9..3d9545d69 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/Paths.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Paths.java @@ -24,12 +24,10 @@ *

    * Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the * Server Object in order to construct the full URL. The Paths MAY be empty, due to - * security - * constraints. + * security constraints. *

    * - * @see OpenAPI - * Specification Paths Object + * @see OpenAPI Specification Paths Object */ public interface Paths extends Constructible, Extensible { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/callbacks/Callback.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/callbacks/Callback.java index 4c058d9c3..e888cc7a7 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/callbacks/Callback.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/callbacks/Callback.java @@ -32,8 +32,7 @@ * used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the * callback operation. * - * @see OpenAPI - * Specification Callback Object + * @see OpenAPI Specification Callback Object */ public interface Callback extends Constructible, Extensible, Reference { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java index 1b1185189..6b295cd3a 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/examples/Example.java @@ -29,8 +29,7 @@ * In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling * implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible. * - * @see OpenAPI - * Specification Example Object + * @see OpenAPI Specification Example Object */ public interface Example extends Constructible, Extensible, Reference { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/headers/Header.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/headers/Header.java index a85d90047..ea4980c90 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/headers/Header.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/headers/Header.java @@ -32,8 +32,7 @@ * Describes a single header parameter for an operation. *

    * - * @see OpenAPI - * Specification Header Object + * @see OpenAPI Specification Header Object */ public interface Header extends Constructible, Extensible

    , Reference
    { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java index d1f1b4aa8..ba26e1ddd 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Contact.java @@ -23,7 +23,7 @@ /** * This interface represents the Contact information for the exposed API. * - * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#contactObject" + * @see OpenAPI Specification Contact Object */ public interface Contact extends Constructible, Extensible { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Info.java index 0005a02b4..03f6231b6 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Info.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Info.java @@ -24,7 +24,7 @@ * This interface represents all the metadata about the API. The metadata may be used by clients if needed, and may be * presented in editing or documentation tools. * - * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#infoObject" + * @see OpenAPI Specification Info Object */ public interface Info extends Constructible, Extensible { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/License.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/License.java index 7844ec482..a0f204f23 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/License.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/License.java @@ -23,7 +23,7 @@ /** * This interface represents the License information for the exposed API. * - * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#licenseObject" + * @see OpenAPI Specification License Object */ public interface License extends Constructible, Extensible { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/links/Link.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/links/Link.java index dd172f59e..fbf2975bf 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/links/Link.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/links/Link.java @@ -39,8 +39,7 @@ * operationRef syntax is preferred for specifications with external references. *

    * - * @see OpenAPI - * Specification Link Object + * @see OpenAPI Specification Link Object */ public interface Link extends Constructible, Extensible, Reference { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Discriminator.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Discriminator.java index 5bb4fa411..461241c1b 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Discriminator.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Discriminator.java @@ -30,9 +30,8 @@ * it. *

    * - * @see OpenAPI - * Specification Discriminator Object + * @see OpenAPI Specification Discriminator + * Object */ public interface Discriminator extends Constructible { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Encoding.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Encoding.java index a5b557271..6f9661636 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Encoding.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Encoding.java @@ -26,8 +26,7 @@ /** * Encoding * - * @see Encoding - * Object + * @see OpenAPI Specification Encoding Object */ public interface Encoding extends Constructible, Extensible { @@ -267,4 +266,4 @@ default Encoding allowReserved(Boolean allowReserved) { */ void setAllowReserved(Boolean allowReserved); -} \ No newline at end of file +} diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MediaType.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MediaType.java index 27ecf2e02..9a5d94b31 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MediaType.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/MediaType.java @@ -29,8 +29,8 @@ * Each Media Type Object provides a schema and examples for the media type identified by its key. *

    * - * @see OpenAPI - * Specification Media Type Object + * @see OpenAPI Specification Media Type + * Object */ public interface MediaType extends Constructible, Extensible { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java index 6a7e45bb8..9e95aa0b8 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java @@ -39,8 +39,7 @@ * Any time a Schema Object can be used, a Reference Object can be used in its place. This allows referencing an * existing definition instead of defining the same Schema again. * - * @see OpenAPI - * Specification Schema Object + * @see OpenAPI Specification Schema Object */ public interface Schema extends Extensible, Constructible, Reference { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java index 2b9fafd43..f0851fe4f 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/XML.java @@ -24,7 +24,7 @@ * A metadata object that allows for more fine-tuned XML model definitions. When using arrays, XML element names are not * inferred (for singular/plural forms) and the name property SHOULD be used to add that information. * - * @see XML Object + * @see OpenAPI Specification XML Object */ public interface XML extends Constructible, Extensible { @@ -221,4 +221,4 @@ default XML wrapped(Boolean wrapped) { return this; } -} \ No newline at end of file +} diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/Parameter.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/Parameter.java index f34728506..bd22a3637 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/Parameter.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/Parameter.java @@ -49,8 +49,7 @@ * For more complex scenarios, the content property can define the media type and schema of the parameter. A parameter * must contain either a schema property, or a content property, but not both. * - * @see OpenAPI - * Specification Parameter Object + * @see OpenAPI Specification Parameter Object */ public interface Parameter extends Constructible, Extensible, Reference { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java index 14ffcee99..1867087c2 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/parameters/RequestBody.java @@ -25,8 +25,7 @@ /** * This interface represents the request body of an operation in which body parameters can be specified. * - * @see requestBody + * @see OpenAPI Specification Request Body * Object */ public interface RequestBody extends Constructible, Extensible, Reference { @@ -124,4 +123,4 @@ default RequestBody required(Boolean required) { return this; } -} \ No newline at end of file +} diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponse.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponse.java index 72e459ba2..865b009ee 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponse.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponse.java @@ -30,7 +30,7 @@ * This interface represents a single response from an API Operation, including design-time, static links to operations * based on the response. * - * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#responseObject" + * @see OpenAPI Specification Response Object */ public interface APIResponse extends Constructible, Extensible, Reference { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponses.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponses.java index 674482b82..eb17f299d 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponses.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/responses/APIResponses.java @@ -26,8 +26,7 @@ * This interface represents the container for the expected responses of an operation. The container maps a HTTP * response code to the expected response. * - * @see Responses - * Object + * @see OpenAPI Specification Responses Object */ public interface APIResponses extends Constructible, Extensible { @@ -141,4 +140,4 @@ default APIResponses defaultValue(APIResponse defaultValue) { return this; } -} \ No newline at end of file +} diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java index bfc279d4b..cb1964ece 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlow.java @@ -25,7 +25,7 @@ /** * Configuration details for a supportde OAuthFlow * - * @see OAuth Flow + * @see OpenAPI Specification OAuth Flow * Object */ public interface OAuthFlow extends Constructible, Extensible { @@ -224,4 +224,4 @@ default OAuthFlow scopes(Map scopes) { **/ Map getScopes(); -} \ No newline at end of file +} diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java index 646c7d460..39143446f 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/OAuthFlows.java @@ -23,7 +23,7 @@ /** * Configuration of the supported OAuthFlows * - * @see OAuthFlows + * @see OpenAPI Specification OAuth Flows * Object */ public interface OAuthFlows extends Constructible, Extensible { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityRequirement.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityRequirement.java index 37f253ccf..d4d3a1b87 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityRequirement.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityRequirement.java @@ -25,9 +25,8 @@ /** * SecurityRequirement * - * @see SecurityRequirement - * Object + * @see OpenAPI Specification Security + * Requirement Object */ public interface SecurityRequirement extends Constructible { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java index e6269ed17..b45a01782 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/security/SecurityScheme.java @@ -24,7 +24,8 @@ /** * SecurityScheme * - * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#security-scheme-object" + * @see OpenAPI Specification Security Scheme + * Object */ public interface SecurityScheme extends Constructible, Extensible, Reference { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/Server.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/Server.java index 62947c9bf..21be1e1f0 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/Server.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/Server.java @@ -25,8 +25,7 @@ /** * An object representing a server. * - * @see Server - * Object + * @see OpenAPI Specification Server Object */ public interface Server extends Constructible, Extensible { @@ -178,4 +177,4 @@ default Server variables(Map variables) { setVariables(variables); return this; } -} \ No newline at end of file +} diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java index d97697d46..ea8b5e8e2 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/servers/ServerVariable.java @@ -25,9 +25,8 @@ /** * An object representing a Server Variable for server URL template substitution. * - * @see ServerVariable - * Object + * @see OpenAPI Specification Server + * Variable Object */ public interface ServerVariable extends Constructible, Extensible { @@ -166,4 +165,4 @@ default ServerVariable description(String description) { return this; } -} \ No newline at end of file +} diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java index d69e833cc..915db28f9 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/tags/Tag.java @@ -26,8 +26,7 @@ *

    * An object to store metadata to be available in the OpenAPI document. * - * @see OpenAPI - * Specification Tag Object + * @see OpenAPI Specification Tag Object */ public interface Tag extends Constructible, Extensible { diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/package-info.java index 6684dbd85..0718528e0 100644 --- a/api/src/main/java/org/eclipse/microprofile/openapi/package-info.java +++ b/api/src/main/java/org/eclipse/microprofile/openapi/package-info.java @@ -13,9 +13,9 @@ /** * A set of Java interfaces, annotations and programming models which allow Java developers to natively produce OpenAPI - * v3 documents from their Jakarta REST applications. + * v3.1 documents from their Jakarta REST applications. */ @org.osgi.annotation.versioning.Version("2.1") @org.osgi.annotation.versioning.ProviderType -package org.eclipse.microprofile.openapi; \ No newline at end of file +package org.eclipse.microprofile.openapi; diff --git a/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc b/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc index f2b8c3d3b..f0879094b 100644 --- a/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc +++ b/spec/src/main/asciidoc/microprofile-openapi-spec.asciidoc @@ -45,12 +45,12 @@ anywhere: on-premises, private cloud, public cloud, etc. For the clients and providers of these services to connect there needs to be a clear and complete contract. Similar to the WSDL contract for legacy Web Services, -the https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md[OpenAPI v3] specification is the contract for +the https://spec.openapis.org/oas/v3.1.0.html[OpenAPI v3.1] specification is the contract for RESTful Services. This MicroProfile specification, called OpenAPI, aims to provide a set of Java interfaces and programming models which allow Java developers to natively produce -OpenAPI v3 documents from their applications written using Jakarta RESTful Web +OpenAPI v3.1 documents from their applications written using Jakarta RESTful Web Services (Jakarta REST). == Architecture @@ -72,8 +72,8 @@ which means that vendors implementing the MP OpenAPI specification must also imp the MP Config specification. There are various ways to inject these configuration values into an MP OpenAPI -framework, including the https://github.com/eclipse/microprofile-config/blob/master/spec/src/main/asciidoc/configsources.asciidoc#default-configources[default ConfigSource] as well as -https://github.com/eclipse/microprofile-config/blob/master/spec/src/main/asciidoc/configsources.asciidoc#custom-configsources[custom ConfigSource]. +framework, including the https://download.eclipse.org/microprofile/microprofile-config-3.1/microprofile-config-spec-3.1.html#default_configsources[default ConfigSource] as well as +https://download.eclipse.org/microprofile/microprofile-config-3.1/microprofile-config-spec-3.1.html#custom_configsources[custom ConfigSource]. Vendors implementing the MP OpenAPI specification can optionally provide additional native ways for these configuration values to be injected into the framework @@ -89,7 +89,7 @@ framework-specific values for configurations that affect implementation behavior For convenience of vendors (and application developers using custom ConfigSources), the full list of supported configuration keys is available as constants in the -https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/OASConfig.java[OASConfig] class. +https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/OASConfig.java[OASConfig] class. ==== Core configurations @@ -205,7 +205,7 @@ been built from the previously described documentation mechanisms. === Annotations -Many of these OpenAPI v3 annotations were derived from the https://github.com/swagger-api/swagger-core[Swagger Core] library, which +Many of these annotations were derived from the https://github.com/swagger-api/swagger-core[Swagger Core] library, which allows for a mostly-mechanical transformation of applications that are using that library and wish to take advantage to the official MP OpenAPI interfaces. @@ -217,52 +217,52 @@ The following annotations are found in the https://github.com/eclipse/microprofi |=== | Annotation | Description -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callback.java[@Callback] | Represents a callback URL that will be invoked. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callbacks.java[@Callbacks] | Represents an array of Callback URLs that can be invoked. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/CallbackOperation.java[@CallbackOperation] | Represents an operation that will be invoked during the callback. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Components.java[@Components] | A container that holds various reusable objects for different aspects of the OpenAPI Specification. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/enums/Explode.java[@Explode] | Enumeration used to define the value of the `explode` property. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/enums/ParameterIn.java[@ParameterIn] | Enumeration representing the parameter's `in` property. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/enums/ParameterStyle.java[@ParameterStyle] | Enumeration for the parameter's `style` property. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/enums/SecuritySchemeIn.java[@SecuritySchemeIn] | Enumeration for the security scheme's `in` property. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/enums/SecuritySchemeType.java[@SecuritySchemeType] | Enumeration for the security scheme's `type` property. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/extensions/Extension.java[@Extension] | Adds an extension with contained properties. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/extensions/Extensions.java[@Extensions] | Adds custom properties to an extension. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/ExternalDocumentation.java[@ExternalDocumentation] | References an external resource for extended documentation. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/headers/Header.java[@Header] | Describes a single header object. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Contact.java[@Contact] | Contact information for the exposed API. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Info.java[@Info] | This annotation encapsulates metadata about the API. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/License.java[@License] | License information for the exposed API. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/links/Link.java[@Link] | Represents a design-time link for a response. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/links/LinkParameter.java[@LinkParameter] | Represents a parameter to pass to the linked operation. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Content.java[@Content] | Provides schema and examples for a particular media type. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DiscriminatorMapping.java[@DiscriminatorMapping] | Used to differentiate between other schemas which may satisfy the payload description. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Encoding.java[@Encoding] | Single encoding definition to be applied to single Schema Object. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/ExampleObject.java[@ExampleObject] | Illustrates an example of a particular content. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Schema.java[@Schema] | Allows the definition of input and output data types. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Schema.java[@SchemaProperty] | Allows the definition of a property nested within a parent @Schema. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/OpenAPIDefinition.java[@OpenAPIDefinition] | General metadata for an OpenAPI definition. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Operation.java[@Operation] | Describes an operation or typically a HTTP method against a specific path. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameter.java[@Parameter] | Describes a single operation parameter. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameters.java[@Parameters] | Encapsulates input parameters. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBody.java[@RequestBody] | Describes a single request body. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBodySchema.java[@RequestBodySchema] | Describes a single request body with schema implementation class. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponse.java[@APIResponse] | Describes a single response from an API operation. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponses.java[@APIResponses] | A container for multiple responses from an API operation. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponseSchema.java[@APIResponseSchema] | Describes a single response with schema implementation class from an API operation. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthFlow.java[@OAuthFlow] | Configuration details for a supported OAuth Flow. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthFlows.java[@OAuthFlows] | Allows configuration of the supported OAuth Flows. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthScope.java[@OAuthScope] | Represents an OAuth scope. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirement.java[@SecurityRequirement] | Specifies a security requirement for an operation. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirements.java[@SecurityRequirements] | Represents an array of security requirements where only one needs to be satisfied. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirementsSet.java[@SecurityRequirementsSet] | Represents an array of security requirements that need to be satisfied. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityScheme.java[@SecurityScheme] | Defines a security scheme that can be used by the operations. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecuritySchemes.java[@SecuritySchemes] | Represents an array of security schemes that can be specified. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Server.java[@Server]| Represents a server used in an operation or used by all operations in an OpenAPI document. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Servers.java[@Servers] | A container for multiple server definitions. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/ServerVariable.java[@ServerVariable] | Represents a server variable for server URL template substitution. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tag.java[@Tag] | Represents a tag for the API endpoint. -| https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tags.java[@Tags] | A container of multiple tags. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callback.java[@Callback] | Represents a callback URL that will be invoked. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callbacks.java[@Callbacks] | Represents an array of Callback URLs that can be invoked. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/CallbackOperation.java[@CallbackOperation] | Represents an operation that will be invoked during the callback. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Components.java[@Components] | A container that holds various reusable objects for different aspects of the OpenAPI Specification. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/enums/Explode.java[@Explode] | Enumeration used to define the value of the `explode` property. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/enums/ParameterIn.java[@ParameterIn] | Enumeration representing the parameter's `in` property. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/enums/ParameterStyle.java[@ParameterStyle] | Enumeration for the parameter's `style` property. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/enums/SecuritySchemeIn.java[@SecuritySchemeIn] | Enumeration for the security scheme's `in` property. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/enums/SecuritySchemeType.java[@SecuritySchemeType] | Enumeration for the security scheme's `type` property. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/extensions/Extension.java[@Extension] | Adds an extension with contained properties. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/extensions/Extensions.java[@Extensions] | Adds custom properties to an extension. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/ExternalDocumentation.java[@ExternalDocumentation] | References an external resource for extended documentation. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/headers/Header.java[@Header] | Describes a single header object. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Contact.java[@Contact] | Contact information for the exposed API. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Info.java[@Info] | This annotation encapsulates metadata about the API. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/License.java[@License] | License information for the exposed API. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/links/Link.java[@Link] | Represents a design-time link for a response. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/links/LinkParameter.java[@LinkParameter] | Represents a parameter to pass to the linked operation. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Content.java[@Content] | Provides schema and examples for a particular media type. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/DiscriminatorMapping.java[@DiscriminatorMapping] | Used to differentiate between other schemas which may satisfy the payload description. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Encoding.java[@Encoding] | Single encoding definition to be applied to single Schema Object. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/ExampleObject.java[@ExampleObject] | Illustrates an example of a particular content. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/Schema.java[@Schema] | Allows the definition of input and output data types. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/SchemaProperty.java[@SchemaProperty] | Allows the definition of a property nested within a parent @Schema. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/OpenAPIDefinition.java[@OpenAPIDefinition] | General metadata for an OpenAPI definition. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Operation.java[@Operation] | Describes an operation or typically a HTTP method against a specific path. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameter.java[@Parameter] | Describes a single operation parameter. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameters.java[@Parameters] | Encapsulates input parameters. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBody.java[@RequestBody] | Describes a single request body. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBodySchema.java[@RequestBodySchema] | Describes a single request body with schema implementation class. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponse.java[@APIResponse] | Describes a single response from an API operation. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponses.java[@APIResponses] | A container for multiple responses from an API operation. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponseSchema.java[@APIResponseSchema] | Describes a single response with schema implementation class from an API operation. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthFlow.java[@OAuthFlow] | Configuration details for a supported OAuth Flow. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthFlows.java[@OAuthFlows] | Allows configuration of the supported OAuth Flows. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/OAuthScope.java[@OAuthScope] | Represents an OAuth scope. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirement.java[@SecurityRequirement] | Specifies a security requirement for an operation. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirements.java[@SecurityRequirements] | Represents an array of security requirements where only one needs to be satisfied. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityRequirementsSet.java[@SecurityRequirementsSet] | Represents an array of security requirements that need to be satisfied. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityScheme.java[@SecurityScheme] | Defines a security scheme that can be used by the operations. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecuritySchemes.java[@SecuritySchemes] | Represents an array of security schemes that can be specified. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Server.java[@Server]| Represents a server used in an operation or used by all operations in an OpenAPI document. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/Servers.java[@Servers] | A container for multiple server definitions. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/servers/ServerVariable.java[@ServerVariable] | Represents a server variable for server URL template substitution. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tag.java[@Tag] | Represents a tag for the API endpoint. +| https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tags.java[@Tags] | A container of multiple tags. |=== ===== Overrides @@ -660,9 +660,9 @@ complete set of models are found in the https://github.com/eclipse/microprofile- ==== OASFactory -The https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java[OASFactory] is used to create all of the elements of an OpenAPI tree. +The https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java[OASFactory] is used to create all of the elements of an OpenAPI tree. -For example, the following snippet creates a simple https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Info.java[Info] element that contains a title, description, and version. +For example, the following snippet creates a simple https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Info.java[Info] element that contains a title, description, and version. [source,java] ---- @@ -671,7 +671,7 @@ OASFactory.createObject(Info.class).title("Airlines").description("Airlines APIs ==== OASModelReader -The https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/OASModelReader.java[OASModelReader] interface allows application developers to bootstrap the OpenAPI model tree +The https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/OASModelReader.java[OASModelReader] interface allows application developers to bootstrap the OpenAPI model tree used by the processing framework. To use it, simply create an implementation of this interface and register it using the `mp.openapi.model.reader` configuration key, where the value is the fully qualified name of the reader class. @@ -700,7 +700,7 @@ which is called once after all other documentation mechanisms have completed. ==== OASFilter -The https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/OASFilter.java[OASFilter] interface allows application developers +The https://github.com/eclipse/microprofile-open-api/blob/main/api/src/main/java/org/eclipse/microprofile/openapi/OASFilter.java[OASFilter] interface allows application developers to receive callbacks for various key OpenAPI elements. The interface has a default implementation for every method, which allows application developers to only override the methods they care about. To use it, simply create an implementation of @@ -787,8 +787,8 @@ where the value can be either `JSON` or `YAML`, to facilitate the toggle between the default `YAML` format and `JSON` format. === Context root behavior -Vendors are required to ensure that the combination of each global https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#serverObject[server] -element and https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathItemObject[pathItem] element resolve to the absolute backend URL of that +Vendors are required to ensure that the combination of each global https://spec.openapis.org/oas/v3.1.0.html#server-object[server] +element and https://spec.openapis.org/oas/v3.1.0.html#path-item-object[pathItem] element resolve to the absolute backend URL of that particular path. If that `pathItem` contains a `servers` element , then this list of operation-level `server` elements replaces the global list of servers for that particular `pathItem`. @@ -825,7 +825,7 @@ It is common that a microservice (A) using MicroProfile OpenAPI will also use ht to make outbound calls into another microservice (B). In this case, we do not want the interface for microservice (B) to appear in microservice (A)'s OAS3 document. -Therefore, vendors are required to exclude from the final OAS3 document any interface annotated with https://github.com/eclipse/microprofile-rest-client/blob/master/api/src/main/java/org/eclipse/microprofile/rest/client/inject/RegisterRestClient.java[org.eclipse.microprofile.rest.client.inject.RegisterRestClient]. +Therefore, vendors are required to exclude from the final OAS3 document any interface annotated with https://download.eclipse.org/microprofile/microprofile-rest-client-3.0/apidocs/org/eclipse/microprofile/rest/client/inject/RegisterRestClient.html[org.eclipse.microprofile.rest.client.inject.RegisterRestClient]. == Limitations @@ -841,7 +841,7 @@ processed languages can be kept to improve performance. === Validation The MP OpenAPI specification does not mandate vendors to validate the resulting -OpenAPI v3 model (after processing the 5 steps previously mentioned), which means +OpenAPI v3.1 model (after processing the 5 steps previously mentioned), which means that the behavior of invalid models is vendor specific (i.e. vendors may choose to ignore, reject, or pass-through invalid inputs).