diff --git a/README.adoc b/README.adoc index 5333be49..57202047 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 a3f9ae0e..abb1d56c 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 7a833649..8e115a97 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 345c979b..2459313f 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 e587bd0f..28b496d0 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 26064b76..46a3bb2b 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 41cdf533..29c85d53 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 c41e93a1..dc18f9cd 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 97cb031a..e14a5e8f 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 4e59d6c1..483bb174 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 ae0468cc..d4138912 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 99c3f561..a566daf2 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 456bf55a..b46fef51 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 7d09b708..776c89e2 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 749fc5eb..9f9ed844 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 036e3ce5..7d5dd78d 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 fda821c9..1dd530ed 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 911af50b..17bbe56e 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 @@ -45,8 +45,7 @@ *

  • {@link Void} to indicate that the schema should not be included at all (this is the default for most parameters) * * - * @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 9a915dd6..66f24c7e 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 @@ -33,8 +33,7 @@ * * This object is an extended subset of the JSON Schema draft specification 2020-12. * - * @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 6ea8f517..634e0af5 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 e41d0d70..d06cddf3 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 c04ed72e..0f07d832 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 1bcea852..ffeeb4fc 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 6f666036..87cbb817 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 0a2f5642..a968d26e 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 31dde7ef..da519359 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 c2c0cdc8..10ab2407 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 6c6907b4..593ce3fb 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 42833aea..03343008 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 78e37121..62bd8f8e 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 d0a8b803..0fe8fb5f 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 db420077..3bd85b21 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 1d8b4a6e..4ca0cdcd 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 1610cb29..5155f134 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 f61c69ec..e0064b6b 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 eaffd8fe..74163d34 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 ef157eeb..0417f372 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 11889360..8e5526ca 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 c17fd6ac..34f8fcee 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 3c05eecd..9a85ad1e 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 f68310ea..174af0d4 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 1022bf59..dc3c0a13 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 3433674e..23ab72a3 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 b1bedad4..48b431c8 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 e611e438..e2838929 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 100a644e..3d9545d6 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 4c058d9c..e888cc7a 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 1b118518..6b295cd3 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 a85d9004..ea4980c9 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 d1f1b4aa..ba26e1dd 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 984cc336..2644aeb8 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 7844ec48..a0f204f2 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 dd172f59..fbf2975b 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 5bb4fa41..461241c1 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 a5b55727..6f966163 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 27ecf2e0..9a5d94b3 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 6a7e45bb..9e95aa0b 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 2b9fafd4..f0851fe4 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 f3472850..bd22a363 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 14ffcee9..1867087c 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 72e459ba..865b009e 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 674482b8..eb17f299 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 bfc279d4..cb1964ec 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 646c7d46..39143446 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 37f253cc..d4d3a1b8 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 e6269ed1..b45a0178 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 62947c9b..21be1e1f 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 d97697d4..ea8b5e8e 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 d69e833c..915db28f 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 6684dbd8..0718528e 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 f2b8c3d3..f0879094 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).