io.swagger.v3.oas.annotations

Annotation Type Operation

@Target(value={METHOD,ANNOTATION_TYPE})
 @Retention(value=RUNTIME)
 @Inherited
public @interface Operation

The annotation may be used to define a resource method as an OpenAPI Operation, and/or to define additional properties for the Operation.

Note: swagger-jaxrs2 reader engine includes by default also methods of scanned resources which are not annotated with @Operation, as long as a jax-rs @Path is defined at class and/or method level, together with the http method annotation (@GET, @POST, etc).

This behaviour is controlled by configuration property `scanAllResources` which defaults to true. By setting this flag to false only @Operation annotated methods are considered.

The following fields can also alternatively be defined at method level (as repeatable annotations in case of arrays), in this case method level annotations take precedence over @Operation annotation fields:

• tags: @Tag
• externalDocs: @ExternalDocumentation
• parameters: @Parameter
• responses: @ApiResponse
• security: @SecurityRequirement
• servers: @Server
• extensions: @Extension
• hidden: @Hidden

See Also:

Operation (OpenAPI specification)

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	deprecated Allows an operation to be marked as deprecated.
String	description A verbose description of the operation.
Extension[]	extensions The list of optional extensions
ExternalDocumentation	externalDocs Additional external documentation for this operation.
boolean	hidden Allows this operation to be marked as hidden
boolean	ignoreJsonView Ignores JsonView annotations while resolving operations and types.
String	method The HTTP method for this operation.
String	operationId The operationId is used by third-party tools to uniquely identify this operation.
Parameter[]	parameters An optional array of parameters which will be added to any automatically detected parameters in the method itself.
RequestBody	requestBody Request body associated to the operation.
ApiResponse[]	responses The list of possible responses as they are returned from executing this operation.
SecurityRequirement[]	security A declaration of which security mechanisms can be used for this operation.
Server[]	servers An alternative server array to service this operation.
String	summary Provides a brief description of this operation.
String[]	tags Tags can be used for logical grouping of operations by resources or any other qualifier.

Element Detail

method

public abstract String method

The HTTP method for this operation.

Returns:

the HTTP method of this operation

Default:

""

tags

public abstract String[] tags

Tags can be used for logical grouping of operations by resources or any other qualifier.

Returns:

the list of tags associated with this operation

Default:

{}

summary

public abstract String summary

Provides a brief description of this operation. Should be 120 characters or less for proper visibility in Swagger-UI.

Returns:

a summary of this operation

Default:

""

description

public abstract String description

A verbose description of the operation.

Returns:

a description of this operation

Default:

""

requestBody

public abstract RequestBody requestBody

Request body associated to the operation.

Returns:

a request body.

Default:

@io.swagger.v3.oas.annotations.parameters.RequestBody

externalDocs

public abstract ExternalDocumentation externalDocs

Additional external documentation for this operation.

Returns:

additional documentation about this operation

Default:

@io.swagger.v3.oas.annotations.ExternalDocumentation

operationId

public abstract String operationId

The operationId is used by third-party tools to uniquely identify this operation.

Returns:

the ID of this operation

Default:

""

parameters

public abstract Parameter[] parameters

An optional array of parameters which will be added to any automatically detected parameters in the method itself.

Returns:

the list of parameters for this operation

Default:

{}

responses

public abstract ApiResponse[] responses

The list of possible responses as they are returned from executing this operation.

Returns:

the list of responses for this operation

Default:

{}

deprecated

public abstract boolean deprecated

Allows an operation to be marked as deprecated. Alternatively use the @Deprecated annotation

Returns:

whether or not this operation is deprecated

Default:

false

security

public abstract SecurityRequirement[] security

A declaration of which security mechanisms can be used for this operation.

Returns:

the array of security requirements for this Operation

Default:

{}

servers

public abstract Server[] servers

An alternative server array to service this operation.

Returns:

the list of servers hosting this operation

Default:

{}

extensions

public abstract Extension[] extensions

The list of optional extensions

Returns:

an optional array of extensions

Default:

{}

hidden

public abstract boolean hidden

Allows this operation to be marked as hidden

Returns:

whether or not this operation is hidden

Default:

false

ignoreJsonView

public abstract boolean ignoreJsonView

Ignores JsonView annotations while resolving operations and types.

Returns:

whether or not to ignore JsonView annotations

Default:

false