org.eclipse.microprofile.openapi.annotations.parameters.RequestBodySchema Maven / Gradle / Ivy
/**
* Copyright (c) 2020 Contributors to the Eclipse Foundation
*
* 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
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* 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.
*
*
* The following annotation usages are equivalent to the OpenAPI annotation scanner runtime.
*
*
* @RequestBody(content = { @Content(schema = @Schema(implementation = MyRequestObject.class)) })
*
* @RequestBodySchema(MyRequestObject.class)
*
*
*
* Any media types that apply to the resource method from either a method-level or class-level
* @Consumes annotation will result in those media types applying to the OpenAPI request body model.
*
*
* This annotation is useful in cases when a single request body schema applies to all media types (as given in
* @Consumes), where it is not possible for class introspection to determine the schema directly.
*
*
* @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();
* }
*
*
* @see RequestBody
* @see OpenAPI
* requestBody Object
**/
@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();
}