Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add RequestBodySchema and APIResponseSchema annotations
Signed-off-by: Michael Edgar <michael@xlate.io>
- Loading branch information
Showing
4 changed files
with
182 additions
and
2 deletions.
There are no files selected for viewing
79 changes: 79 additions & 0 deletions
79
.../main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBodySchema.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,79 @@ | ||
| /** | ||
| * Copyright (c) 2020 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.parameters; | ||
|
|
||
| import java.lang.annotation.ElementType; | ||
| import java.lang.annotation.Inherited; | ||
| import java.lang.annotation.Retention; | ||
| import java.lang.annotation.RetentionPolicy; | ||
| import java.lang.annotation.Target; | ||
|
|
||
| /** | ||
| * Provides a reference to a class that (after introspection) describes the schema | ||
| * for a single request body. This annotation provides a short-hand way to specify a | ||
| * simple request body that would otherwise be specified using {@link RequestBody @RequestBody} | ||
| * and that typically could not be determined by scanning the resource method alone. | ||
| * | ||
| * <p> | ||
| * The following annotation usages are equivalent to the OpenAPI annotation scanner runtime. | ||
| * | ||
| * <pre> | ||
| * @RequestBody(content = { @Content(schema = @Schema(implementation = MyRequestObject.class)) }) | ||
| * | ||
| * @RequestBodySchema(MyRequestObject.class) | ||
| * </pre> | ||
| * | ||
| * <p> | ||
| * Any media types that apply to the resource method from either a method-level or class-level | ||
| * <code>@Consumes</code> annotation will result in those media types applying to the OpenAPI | ||
| * request body model. | ||
| * | ||
| * <p> | ||
| * This annotation is useful in cases when a single request body schema applies to all media types (as | ||
| * given in <code>@Consumes</code>), where it is not possible for class introspection to | ||
| * determine the schema directly. | ||
| * | ||
| * <pre> | ||
| * @PUT | ||
| * @Path("{id}") | ||
| * @RequestBodySchema(MyRequestObject.class) | ||
| * public Response updateItem(@PathParam("{id}") long id, InputStream rawData) { | ||
| * MyRequestObject entity = service.deserialize(rawData); | ||
| * service.persist(entity); | ||
| * | ||
| * return Response.status(204).build(); | ||
| * } | ||
| * </pre> | ||
| * | ||
| * @see RequestBody | ||
| * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#requestBodyObject">OpenAPI requestBody Object</a> | ||
| **/ | ||
| @Target({ ElementType.PARAMETER, ElementType.METHOD }) | ||
| @Retention(RetentionPolicy.RUNTIME) | ||
| @Inherited | ||
| public @interface RequestBodySchema { | ||
|
|
||
| /** | ||
| * Provides a Java class as implementation for this schema. The class will | ||
| * undergo introspection to determine any applicable Schema attributes to be | ||
| * applied to the OpenAPI request body model. | ||
| * | ||
| * @return a class that implements this schema | ||
| **/ | ||
| Class<?> value(); | ||
|
|
||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
99 changes: 99 additions & 0 deletions
99
...c/main/java/org/eclipse/microprofile/openapi/annotations/responses/APIResponseSchema.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,99 @@ | ||
| /** | ||
| * Copyright (c) 2020 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.responses; | ||
|
|
||
| import java.lang.annotation.ElementType; | ||
| import java.lang.annotation.Inherited; | ||
| import java.lang.annotation.Retention; | ||
| import java.lang.annotation.RetentionPolicy; | ||
| import java.lang.annotation.Target; | ||
|
|
||
| /** | ||
| * The APIResponseSchema annotation corresponds to an individual schema in the OpenAPI | ||
| * Response model object which describes a single response from an API Operation. This | ||
| * annotation provides a short-hand way to specify a simple response that would otherwise | ||
| * be specified using {@link APIResponse @APIResponse} and that typically could not be determined by | ||
| * scanning the resource method alone. | ||
| * | ||
| * <p> | ||
| * The following annotation usages are equivalent to the OpenAPI annotation scanner runtime. | ||
| * | ||
| * <pre> | ||
| * @APIResponse(content = { @Content(schema = @Schema(implementation = MyResponseObject.class)) }) | ||
| * | ||
| * @APIResponseSchema(MyResponseObject.class) | ||
| * </pre> | ||
| * | ||
| * <p> | ||
| * When this annotation is applied to a method the response is added to the responses | ||
| * defined in the corresponding OpenAPI operation with a default response code and description | ||
| * that correspond to the method's HTTP method annotation and return type. Any media types that | ||
| * apply to the resource method from either a method-level or class-level <code>@Produces</code> | ||
| * annotation will result in those media types applying to the OpenAPI response model. | ||
| * | ||
| * <p> | ||
| * The default response code shall be determined using REST conventions as follows: | ||
| * <ul> | ||
| * <li>If the method's return type is <code>void</code> and the HTTP method is <code>@POST</code>, | ||
| * the status code will be <code>201</code> and the description will be "Created" | ||
| * <li>Otherwise, if the method's return type is <code>void</code> the method does not list a JAX-RS | ||
| * <code>AsyncResponse</code> parameter, the status code will be <code>204</code> and the description | ||
| * will be "No Content". | ||
| * <li>Otherwise, the status code will be <code>200</code> and the description will be "OK". | ||
| * </ul> | ||
| * | ||
| * <pre> | ||
| * @GET | ||
| * @Path("{id}") | ||
| * @APIResponseSchema(value = MyResponseObject.class, responseDescription = "Success", responseCode = "200") | ||
| * public Response getById(@PathParam("{id}") long id) { | ||
| * MyResponseObject entity = service.load(id); | ||
| * return Response.status(200).entity(entity).build(); | ||
| * } | ||
| * </pre> | ||
| * | ||
| * @see APIResponse | ||
| * @see "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#responseObject" | ||
| * | ||
| **/ | ||
| @Target({ ElementType.METHOD }) | ||
| @Retention(RetentionPolicy.RUNTIME) | ||
| @Inherited | ||
| public @interface APIResponseSchema { | ||
|
|
||
| /** | ||
| * Provides a Java class as implementation for this schema. The class will | ||
| * undergo introspection to determine any applicable Schema attributes to be | ||
| * applied to the OpenAPI response model. | ||
| * | ||
| * @return a class that implements this schema | ||
| **/ | ||
| Class<?> value(); | ||
|
|
||
| /** | ||
| * A short description of the response. It is a REQUIRED property. | ||
| * | ||
| * @return description of the response. | ||
| **/ | ||
| String responseDescription(); | ||
|
|
||
| /** | ||
| * The HTTP response code, or 'default', for the supplied response. May only have 1 default entry. | ||
| * | ||
| * @return HTTP response code for this response instance or default | ||
| **/ | ||
| String responseCode() default "default"; | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters