Skip to content

Commit

Permalink
Merge branch 'main' into 587-encoding
Browse files Browse the repository at this point in the history
  • Loading branch information
benjamin-confino committed Jun 10, 2024
2 parents 4207f81 + bd7e934 commit d2637fb
Show file tree
Hide file tree
Showing 30 changed files with 910 additions and 72 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,15 @@
*/
Callback[] callbacks() default {};

/**
* An object to hold reusable Path Item Objects.
*
* @return the reusable PathItem objects.
*
* @since 4.0
*/
PathItem[] pathItems() default {};

/**
* List of extensions to be added to the {@link org.eclipse.microprofile.openapi.models.Components Components} model
* corresponding to the containing annotation.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,15 @@
*/
ExternalDocumentation externalDocs() default @ExternalDocumentation;

/**
* An array of webhook definitions which the API may be instructed to call using out-of-band mechanisms.
*
* @return the array of webhooks
*
* @since 4.0
*/
PathItem[] webhooks() default {};

/**
* An element to hold a set of reusable objects for different aspects of the OpenAPI Specification (OAS).
*
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
/*
* Copyright (c) 2024 Contributors to the Eclipse Foundation
* <p>
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* <p>
* http://www.apache.org/licenses/LICENSE-2.0
* <p>
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.eclipse.microprofile.openapi.annotations;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
import org.eclipse.microprofile.openapi.annotations.servers.Server;

/**
* Describes a set of operations available on a single path.
*
* @since 4.0
*/
@Target({})
@Retention(RetentionPolicy.RUNTIME)
public @interface PathItem {

/**
* The name of the Path Item object, used as the map key when the path item is used under
* {@link Components#pathItems()} or {@link OpenAPIDefinition#webhooks()}
*
* @return the path item name
*/
String name();

/**
* Reference value to a PathItem object.
* <p>
* This property provides a reference to an object defined elsewhere.
* <p>
* Unlike {@code ref} on most MP OpenAPI annotations, this property is <em>not</em> mutually exclusive with other
* properties.
*
* @return reference to a path item object definition
**/
String ref() default "";

/**
* The summary of the path item.
*
* @return the summary
*/
String summary() default "";

/**
* The description of the path item.
*
* @return the description
*/
String description() default "";

/**
* The operations available under this Path Item.
* <p>
* The {@link PathItemOperation#method() method} MUST be defined for each operation.
*
* @return the list of operations
*/
PathItemOperation[] operations() default {};

/**
* A list of servers to be used for this Path Item, overriding those defined for the whole API.
*
* @return the list of servers
*/
Server[] servers() default {};

/**
* A list of parameters which apply to all operations under this path item.
*
* @return the list of parameters
*/
Parameter[] parameters() default {};

/**
* List of extensions to be added to the {@link org.eclipse.microprofile.openapi.models.PathItem PathItem} model
* corresponding to the containing annotation.
*
* @return the list of extensions
*/
Extension[] extensions() default {};
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
/*
* Copyright (c) 2024 Contributors to the Eclipse Foundation
* <p>
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* <p>
* http://www.apache.org/licenses/LICENSE-2.0
* <p>
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.eclipse.microprofile.openapi.annotations;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import org.eclipse.microprofile.openapi.annotations.callbacks.Callback;
import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirementsSet;
import org.eclipse.microprofile.openapi.annotations.servers.Server;
import org.eclipse.microprofile.openapi.annotations.tags.Tag;

/**
* Describes an Operation
* <p>
* This annotation is only used for operations defined under a {@link PathItem}. For operations provided by the API
* itself, it's more common to use the {@link Operation} annotation applied to a Jakarta REST resource method instead.
*
* @since 4.0
*/
@Target({})
@Retention(RetentionPolicy.RUNTIME)
public @interface PathItemOperation {

/**
* The HTTP method for this operation.
*
* @return the HTTP method of this operation
**/
String method();

/**
* The tags which apply to this operation.
*
* @return the list of tags
*/
Tag[] tags() default {};

/**
* Provides a brief description of what this operation does.
*
* @return a summary of this operation
**/
String summary() default "";

/**
* A verbose description of the operation behavior. CommonMark syntax MAY be used for rich text representation.
*
* @return a description of this operation
**/
String description() default "";

/**
* Additional external documentation for this operation.
*
* @return external documentation associated with this operation instance
**/
ExternalDocumentation externalDocs() default @ExternalDocumentation();

/**
* Unique string used to identify the operation. The id MUST be unique among all operations described in the API.
* <p>
* Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to
* follow common programming naming conventions.
* </p>
*
* @return the ID of this operation
**/
String operationId() default "";

/**
* An array of parameters applicable for this operation.
* <p>
* The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and
* location.
* </p>
*
* @return the list of parameters for this operation
**/
Parameter[] parameters() default {};

/**
* The request body for this operation.
*
* @return the request body of this operation
**/
RequestBody requestBody() default @RequestBody();

/**
* The list of possible responses that can be returned when executing this operation.
*
* @return the list of responses for this operation
**/
APIResponse[] responses() default {};

/**
* A list of possible out-of-band callbacks related to this operation. Each entry represents a set of requests that
* may be initiated by the API provided and an expression, evaluated at runtime, that identifies the URL used to
* make those requests.
*
* @return the list of callbacks for this operation
*/
Callback[] callbacks() default {};

/**
* Allows an operation to be marked as deprecated
* <p>
* Consumers SHOULD refrain from usage of a deprecated operation.
* </p>
*
* @return whether or not this operation is deprecated
**/
boolean deprecated() default false;

/**
* A declaration of which security mechanisms can be used for this callback operation. Only one of the security
* requirement objects need to be satisfied to authorize a request.
* <p>
* Adding a {@code SecurityRequirement} to this array is equivalent to adding a {@code SecurityRequirementsSet}
* containing a single {@code SecurityRequirement} to {@link #securitySets()}.
* <p>
* This definition overrides any declared top-level security. To remove a top-level security declaration, an empty
* array can be used.
*
* @return the list of security mechanisms for this operation
*/
SecurityRequirement[] security() default {};

/**
* A declaration of which security mechanisms can be used for this callback operation. All of the security
* requirements within any one of the sets needs needs to be satisfied to authorize a request.
* <p>
* This definition overrides any declared top-level security. To remove a top-level security declaration, an empty
* array can be used.
* <p>
* Including an empty set within this list indicates that the other requirements are optional.
*
* @return the list of security mechanisms for this operation
*/
SecurityRequirementsSet[] securitySets() default {};

/**
* A list of servers to be used for this operation, overriding those defined for the parent path item or for the
* whole API.
*
* @return the list of servers
*/
Server[] servers() default {};

/**
* List of extensions to be added to the {@link org.eclipse.microprofile.openapi.models.Operation Operation} model
* corresponding to the containing annotation.
*
* @return array of extensions
*/
Extension[] extensions() default {};
}
Original file line number Diff line number Diff line change
Expand Up @@ -70,12 +70,23 @@
* Reference value to a Callback object.
* <p>
* This property provides a reference to an object defined elsewhere. This property and all other properties are
* mutually exclusive. If other properties are defined in addition to the ref property then the result is undefined.
* mutually exclusive. If other properties are defined in addition to the {@code ref} property then the result is
* undefined.
*
* @return reference to a callback object definition
**/
String ref() default "";

/**
* Reference value to a Path Item object, to be referenced by the Callback object.
* <p>
* This property provides a reference to a Path Item object defined elsewhere. {@code #callbackUrlExpression()} is
* REQUIRED when this property is set. The referenced Path Item will be used for the URL expression specified.
*
* @since 4.0
*/
String pathItemRef() default "";

/**
* List of extensions to be added to the {@link org.eclipse.microprofile.openapi.models.callbacks.Callback Callback}
* model corresponding to the containing annotation.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,6 @@
* </pre>
*/

@org.osgi.annotation.versioning.Version("1.1")
@org.osgi.annotation.versioning.Version("1.2")
@org.osgi.annotation.versioning.ProviderType
package org.eclipse.microprofile.openapi.annotations.callbacks;
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,9 @@
/**
* Reference value to a Header object.
* <p>
* This property provides a reference to an object defined elsewhere. This property and all other properties are
* mutually exclusive. If other properties are defined in addition to the ref property then the result is undefined.
* This property provides a reference to an object defined elsewhere. This property may be used with
* {@link #description()} but is mutually exclusive with all other properties. If properties other than
* {@code description} are defined in addition to the {@code ref} property then the result is undefined.
*
* @return reference to a header
**/
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -96,8 +96,9 @@
/**
* Reference value to a Link object.
* <p>
* This property provides a reference to an object defined elsewhere. This property and all other properties are
* mutually exclusive. If other properties are defined in addition to the ref property then the result is undefined.
* This property provides a reference to an object defined elsewhere. This property may be used with
* {@link #description()} but is mutually exclusive with all other properties. If properties other than
* {@code description} are defined in addition to the {@code ref} property then the result is undefined.
*
* @return reference to a link
**/
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,10 @@
/**
* Reference value to an Example object.
* <p>
* This property provides a reference to an object defined elsewhere. This property and all other properties are
* mutually exclusive. If other properties are defined in addition to the ref property then the result is undefined.
* This property provides a reference to an object defined elsewhere. This property may be used with
* {@link #description()} and {@link #summary()} but is mutually exclusive with all other properties. If properties
* other than {@code description} and {@code summary} are defined in addition to the {@code ref} property then the
* result is undefined.
*
* @return reference to an example
**/
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,5 +34,5 @@
* </pre>
*/

@org.osgi.annotation.versioning.Version("1.1")
@org.osgi.annotation.versioning.Version("1.2")
package org.eclipse.microprofile.openapi.annotations;
Original file line number Diff line number Diff line change
Expand Up @@ -200,8 +200,9 @@
/**
* Reference value to a Parameter object.
* <p>
* This property provides a reference to an object defined elsewhere. This property and all other properties are
* mutually exclusive. If other properties are defined in addition to the ref property then the result is undefined.
* This property provides a reference to an object defined elsewhere. This property may be used with
* {@link #description()} but is mutually exclusive with all other properties. If properties other than
* {@code description} are defined in addition to the {@code ref} property then the result is undefined.
*
* @return reference to a parameter
**/
Expand Down
Loading

0 comments on commit d2637fb

Please sign in to comment.