Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow ref with description and summary #618

Merged
merged 1 commit into from
Jun 4, 2024
Merged

Allow ref with description and summary #618

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callback.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,8 @@
* 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
**/
Expand Down
5 changes: 3 additions & 2 deletions api/src/main/java/org/eclipse/microprofile/openapi/annotations/headers/Header.java
View file
Open in desktop
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
5 changes: 3 additions & 2 deletions api/src/main/java/org/eclipse/microprofile/openapi/annotations/links/Link.java
View file
Open in desktop
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
6 changes: 4 additions & 2 deletions api/src/main/java/org/eclipse/microprofile/openapi/annotations/media/ExampleObject.java
View file
Open in desktop
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
5 changes: 3 additions & 2 deletions api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/Parameter.java
View file
Open in desktop
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
5 changes: 3 additions & 2 deletions api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBody.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,8 +74,9 @@
/**
* Reference value to a RequestBody 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 request body
**/
Expand Down
5 changes: 3 additions & 2 deletions api/src/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponse.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,8 +128,9 @@
/**
* Reference value to a Response 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 response
**/
Expand Down
5 changes: 3 additions & 2 deletions api/src/main/java/org/eclipse/microprofile/openapi/annotations/security/SecurityScheme.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,8 +132,9 @@
/**
* Reference value to a SecurityScheme 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 security scheme
**/
Expand Down
5 changes: 3 additions & 2 deletions api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tag.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,8 +101,9 @@
/**
* Reference value to a Tag 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 tag
**/
Expand Down
7 changes: 4 additions & 3 deletions api/src/main/java/org/eclipse/microprofile/openapi/models/Reference.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,9 +53,10 @@ public interface Reference<T extends Reference<T>> {
* <code>response.setRef("NotFound"); // #/components/responses/NotFound</code>
* </pre>
* <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 reference property then the result is
* undefined.
* This property provides a reference to an object defined elsewhere. This property may be used alongside
* {@code description} and {@code summary} if they exist on the object, but is mutually exclusive with all other
* properties. If properties other than {@code description} and {@code summary} are defined in addition to the
* reference property then the result is undefined.
*
* @param ref
* a reference to a T object in the components section of this OpenAPI document or a JSON pointer to
Expand Down
41 changes: 33 additions & 8 deletions tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/JAXRSApp.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,10 @@
@APIResponse(name = "FoundBookings", responseCode = "200",
description = "Bookings retrieved",
content = @Content(schema = @Schema(type = SchemaType.ARRAY,
implementation = Booking.class)))
implementation = Booking.class))),
@APIResponse(name = "FoundBookingsARef",
ref = "#/components/responses/FoundBookings",
description = "Found Bookings Reference")
},
parameters = {
@Parameter(name = "departureDate", in = ParameterIn.QUERY,
Expand All @@ -147,7 +150,10 @@
@Parameter(name = "username", in = ParameterIn.QUERY,
description = "The name that needs to be deleted",
schema = @Schema(type = SchemaType.STRING),
required = true)
required = true),
@Parameter(name = "usernameARef",
ref = "#/components/parameters/username",
description = "username reference")
},
examples = {
@ExampleObject(name = "review", summary = "External review example",
Expand All @@ -156,13 +162,21 @@
extensions = @Extension(name = "x-example-object",
value = "test-example-object")),
@ExampleObject(name = "user", summary = "External user example",
externalValue = "http://foo.bar/examples/user-example.json")
externalValue = "http://foo.bar/examples/user-example.json"),
@ExampleObject(name = "userARef",
ref = "#/components/examples/user",
description = "User reference",
summary = "Referenced example")
},
requestBodies = {
@RequestBody(name = "review",
content = @Content(mediaType = MediaType.APPLICATION_JSON,
schema = @Schema(implementation = Review.class)),
required = true, description = "example review to add")
required = true,
description = "example review to add"),
@RequestBody(name = "reviewARef",
ref = "#/components/requestBodies/review",
description = "Review reference")
},
headers = {
@Header(name = "Max-Rate", description = "Maximum rate",
Expand All @@ -173,28 +187,39 @@
value = "test-header")),
@Header(name = "Request-Limit",
description = "The number of allowed requests in the current period",
schema = @Schema(type = SchemaType.INTEGER))
schema = @Schema(type = SchemaType.INTEGER)),
@Header(name = "Request-Limit-ARef",
ref = "#/components/headers/Request-Limit",
description = "Request-Limit reference")
},
securitySchemes = {
@SecurityScheme(securitySchemeName = "httpTestScheme",
description = "user security scheme",
type = SecuritySchemeType.HTTP,
scheme = "testScheme")
scheme = "testScheme"),
@SecurityScheme(securitySchemeName = "httpTestSchemeARef",
ref = "#/components/securitySchemes/httpTestScheme",
description = "httpTestScheme reference")
},
links = {
@Link(name = "UserName",
description = "The username corresponding to provided user id",
operationId = "getUserByName",
parameters = @LinkParameter(name = "userId",
expression = "$request.path.id"))
expression = "$request.path.id")),
@Link(name = "UserNameARef",
ref = "#/components/links/UserName",
description = "UserName reference")
},
callbacks = {
@Callback(name = "GetBookings",
callbackUrlExpression = "http://localhost:9080/airlines/bookings",
operations = @CallbackOperation(summary = "Retrieve all bookings for current user",
responses = {
@APIResponse(ref = "FoundBookings")
}))
})),
@Callback(name = "GetBookingsARef",
ref = "#/components/callbacks/GetBookings")
},
extensions = @Extension(name = "x-components", value = "test-components")),
extensions = @Extension(name = "x-openapi-definition", value = "test-openapi-definition"))
Expand Down
Loading
Loading