-
Notifications
You must be signed in to change notification settings - Fork 82
Annotation Samples
The Callback annotation represents a callback URL that will be invoked.
@Callback(name = "myCallback",
callBackUrlExpression = "www.myurl.com",
callBackOperation = { @CallBackOperation(method = "POST")}
)The Callbacks annotation represents an array of Callback URLs that can be invoked.
@Callbacks( value = {@Callback(name = "myCallback")})The CallbackOperation annotation represents an operation that will be invoked during the callback.
@CallbackOperation( method = "POST",
summary = "A Brief Description Of What The MethodDoes",
description = "A verbose description of the callback operation behavior",
externalDocs = @ExternalDocumentation(description = "A short description of the target documentation.",
url = "www.urlfortargetdocumentation.com"
),
parameters = { @Parameter(name = "Parameter's name")},
requestBody = @RequestBody(description = "A brief description of the request body"),
responses = { @APIResponse(reponseCode = "200")},
security = { @SecurityRequirement(name = "oauth2",
scopes = "read:reviews"
)},
extension = { @Extension(name = "x-header",
value = "The extension value"
)}
)The Components annotation is a container that holds various reusable objects for different aspects of the OpenAPI Specification.
@Components(schemas = {@Schema(name = "the name of the schema")},
responses = {@APIResponse(reponseCode = "200")},
parameter = {@Parameter(name = "Parameter's name")},
examples = {@ExampleObject(name = "Example object name")},
requestBodies = {@RequestBody(description = "A brief description of the request body")},
headers = {@Header(name = "the header's name")},
securitySchemes = {@SecurityScheme(securitySchemeName = "oauth2")},
links = {@Links(name = "the link's name")},
callbacks = {@Callback(name = "myCallback")}
) The Extension annotation adds an extension with contained properties.
@Extension( name = "x-header",
value = "The extension value"
)The Extensions annotation adds custom properties to an extension.
@Extensions(extensions = {@Extension( name = "x-header",
value = "The extension value")}
)The ExternalDocumentation annotation references an external resource for extended documentation.
@ExternalDocumentation( description = "A short description of the target documentation.",
url = "www.urlfortargetdocumentation.com"
)The Header annotation describes a single header object.
@Header(name = "the header's name",
description = "the header's description",
schema = @Schema(name = "the name of schema"),
required = true,
deprecated = true,
allowEmptyValue = true
)The Contact annotation describes the contact information for the exposed API.
@Contact(name = "The name of the contact",
url = "www.urlofcontact.com",
email = "[email protected]"
)The Info annotation encapsulates metadata about the API.
@Info(title = "My Application Title",
description = "My applicatoin description",
termsOfService = "My application's terms of service",
contact = @Contact(name = "The name of the contact",
url = "www.urlofcontact.com",
email = "[email protected]"
),
license = @License(name = "The license name used for the API."),
version = "application version number"
)The License annotation describes the license information for the exposed API.
@License(name = "The license name used for the API.",
url = "www.myurlformylicense.com"
)The Link annotation represents a design-time link for a response.
@Link( name = "the link's name",
operationRef = "an operation ref",
parameters = {@LinkParameter(name = "the parameter's name")},
description = "the link's description",
requestBody = "requestBody of the link",
server = @Server(url = "www.serverurl.com/v1/{myServerVariable1}/{myServerVariable1}",
variables = {@ServerVariable(name = "myServerVariable",
defaultValue = "TOM")}
)
)The LinkParameter annotation represents a parameter to pass to the linked operation.
@LinkParameter(name = "The parameter's name",
expression = "the parameter's literal value or expression"
)The Content annotation provides schema and examples for a particular media type.
@Content(mediaType = "application/x-www-form-urlencoded",
examples = { @ExampleObject(name = "Example object name")},
schema = @Schema(name = "the name of schema"),
encoding = @Encoding(name = "the name of this encoding instance")
)The DiscriminatorMapping used to differentiate between other schemas which may satisfy the payload description.
@DiscriminatorMapping( value = "the property value that gets mapped to schema",
schema = @Schema(name = "the name of the schema")
)The Encoding annotation describes a single encoding definition to be applied to single Schema Object.
@Encoding(name = "the name of this encoding instance",
contentType = "text/plain",
style = "spaceDelimited",
explode = true,
allowReserved = true,
headers= { @Header(name = "the header's name")}
)The ExampleObject annotation illustrates an example of a particular content.
@ExampleObject( name = "Example object name",
summary = "a summary of this example",
description ="a description of this example",
value = "the value of the example",
)The Schema annotation allows the definition of input and output data types.
@Schema(name = "MyMusic",
title = "get all music",
description = "POJO that represents a music collection",
implementation = Review.class,
not = Movie.class, //MUST be of a Schema Object and not a standard JSON Schema
oneOf = {},
anyOf = {Artists.class, Albums.class, Genre.class},
allOf = {},
multipleOf = 2.0,
maximum = "10000",
exclusiveMaximum = true,
minimum = 0,
exclusiveMinimum = false,
maxLength = 1000000,
minimum = 2,
pattern = "",
maxProperties = 0,
minProperties = 0,
requiredProperties = {},
required = false,
format = "int32",
nullable = true,
readOnly = true,
writeOnly = false,
example = "provide an example of how this Schema can be used, cannot be naturally represented in JSON or YAML",
externalDocs = @ExternalDocumentation(url = "www.externaldocurl.com",
description = "This is the description"),
deprecated = false,
type = SchemaType.ARRAY,
enumeration = {},
defaultValue = "",
discriminatorProperty = "music_type",
discriminatorMapping = @DiscriminatorMapping(value = "indie",
shema = @Schema(title = "indieMusic")),
hidden = false,
maxItems = 500,
minItems = 0,
uniqueItems = false
)The OpenAPIDefinition annotation provides general metadata for an OpenAPI definition.
@OpenAPIDefinition(info = @Info(title = "Music Title",
contact = @Contact(name = "Mr. X",
email = "[email protected]"),
version = "3.0.0"),
tags = {@Tag(name = "MusicType"),
@Tag(name = "Artists")},
servers = {@Server(url = "www.serverurl.com/v1/{myServerVariable}",
variables = {@ServerVariable(name = "{myServerVariable}",
defaultValue = "Rachel")})},
security = @SecurityRequirement(name = "ouath2",
scopes = "read:reviews"),
externalDocs = @ExternalDocumentation(url = "www.externaldocurl.com",
description = "url used for external documents"),
components = @Components(schemas = @Schema(title = "Music"))
)The Operation annotation describes an operation or typically a HTTP method against a specific path.
@Operation(operationId = "getAllSongs",
summary = "get all of the classified songs",
description = "This operation retrieves songs from the hidden database",
deprecated = false,
hidden = true
)The Parameter annotation describes a single operation parameter.
@Parameter(name = "musicAlbums",
in = ParameterIn.PATH,
description = "name of the music albums for reviews",
required = true,
deprecated = false,
allowEmptyValue = false,
style = ParameterStyle.LABEL,
explode = Explode.FALSE,
allowReserved = false,
schema = @Schema(title = "Music"),
content = @Content(schema = @Schema(title = "Music")),
hidden = false,
examples = {@ExampleObject(name = "1989"),
@ExampleObject(name = "Fearless")},
example = "Baby"
)The Parameters annotation encapsulates input parameters.
@Parameters(value = {@Parameter(name = "music albums"),
@Parameter(name = "Artists")}
)The RequestBody annotation describes a single request body.
@RequestBody(description = "A brief description of the request body",
content = { @Content(mediaType = "application/x-www-form-urlencoded",
encoding = @Encoding(name = "the name of this encoding instance")
)},
name = "Request body name",
required = true,
)The APIResponse annotation describes a single response from an API operation.
@APIResponse(reponseCode = "200",
description = "A simple array response",
headers = @Header(ref = "#/components/headers/APIResponse"),
links = @Link(ref = "#/components/links/APIResponse"),
content = @Content(schema = @Schema(title = "Music")),
name = "APIResponsetoMusic"
)The APIResponses annotation acts as a container for multiple responses from an API operation.
@APIResponses(value = {@APIResponse(reponseCode = "201",
description = "A simple array response"),
@APIResponse(reponseCode = "202",
description = "A complex array response")}
)The OAuthFlow annotation defines the configuration details for a supported OAuth Flow.
@OAuthFlow(authorizationUrl = "https://example.com/api/oauth/dialog",
tokenUrl = "https://example.com/api/oauth/token",
refreshUrl = "https://example.com/api/oauth/newtoken",
scopes = @OAuthScope(name = "read:reviews",
description = "read a review")
)The OAuthFlows annotation allows configuration of the supported OAuth Flows.
@OAuthFlows(implicit = @OAuthFlow(authorizationUrl = "https://example.com/api/oauth/dialog",
tokenUrl = "https://example.com/api/oauth/token",
refreshUrl = "https://example.com/api/oauth/newtoken",
scopes = @OAuthScope(name = "read:reviews")),
password = @OAuthFlow(authorizationUrl = "https://example.com/api/oauth/dialog",
tokenUrl = "https://example.com/api/oauth/token",
scopes = @OAuthScope(name = "read:reviews")),
clientCredentials = @OAuthFlow(authorizationUrl = "https://example.com/api/oauth/dialog",
tokenUrl = "https://example.com/api/oauth/token",
scopes = @OAuthScope(name = "read:reviews")),
authorizationCode = @OAuthFlow(authorizationUrl = "https://example.com/api/oauth/dialog",
tokenUrl = "https://example.com/api/oauth/token",
scopes = @OAuthScope(name = "read:reviews"))
)The OAuthScope annotation represents an OAuth scope.
@OAuthScope(name = "read:reviews",
description = "read a review"
)The SecurityRequirement annotation specifies a security requirement for an operation.
@SecurityRequirement(name = "ouath2",
scopes = "read:reviews"
)The SecurityRequirements annotation represents an array of security requirements where only one needs to be satisfied.
@SecurityRequirements(value = {@SecurityRequirement(name = "api_key"),
@SecurityRequirement(name = "ouath2", scopes = "read:reviews")}
)The SecurityRequirementsSet annotation represents an array of security requirements that need to be satisfied.
@SecurityRequirementsSet(value = {@SecurityRequirement(name = "api_key"),
@SecurityRequirement(name = "ouath2",
scopes = "read:reviews")}
)The SecurityScheme annotation defines a security scheme that can be used by the operations.
@SecurityScheme(securitySchemeName = "oauth2",
type = SecuritySchemeType.OAUTH2,
description = "Authentication needed for this operation",
flows = @OAuthFlows(implicit = @OAuthFlow(authorizationUrl = "https://example.com/api/oauth/dialog",
tokenUrl = "https://example.com/api/oauth/token",
refreshUrl = "https://example.com/api/oauth/newtoken",
scopes = @OAuthScope(name = "read:music")),
password = @OAuthFlow(authorizationUrl = "https://example.com/api/oauth/dialog",
tokenUrl = "https://example.com/api/oauth/token",
scopes = @OAuthScope(name = "read:music")),
clientCredentials = @OAuthFlow(authorizationUrl = "https://example.com/api/oauth/dialog",
tokenUrl = "https://example.com/api/oauth/token",
scopes = @OAuthScope(name = "read:music")),
authorizationCode = @OAuthFlow(authorizationUrl = "https://example.com/api/oauth/dialog",
tokenUrl = "https://example.com/api/oauth/token",
scopes = @OAuthScope(name = "read:music")))
)The SecuritySchemes annotation represents an array of security schemes that can be specified.
@SecuritySchemes(value = {@SecurityScheme(securitySchemeName = "api_key",
type = SecuritySchemeType.APIKEY,
apiKeyName = "api_key",
in = SecuritySchemeIn.HEADER),
@SecurityScheme(securitySchemeName = "http_secure",
type = SecuritySchemeType.HTTP,
scheme = "bearer",
bearerFormat = "JWT"),
@SecurityScheme(securitySchemeName = "openIdConnectUrl",
type = SecuritySchemeType.OPENIDCONNECT,
openIdConnectUrl = "https://example.com/openidconnect")}
)The Server annotation represents a server used in an operation or used by all operations in an OpenAPI document.
@Server(url = "www.serverurl.com/v1/{myServerVariable}/{myServerVariable1}",
description = "This is a description of the server",
variables = {@ServerVariable(name = "myServerVariable",
defaultValue = "Rachel")
@ServerVariable(name = "myServerVariable1",
defaultValue = "Bob")}
)The Servers annotation a container for multiple server definitions.
@Servers(value = {@Server(url = "www.serverurl.com/v1/{myServerVariable}",
variables = {@ServerVariable(name = "{myServerVariable}",
defaultValue = "Rachel")}),
@Server(url = "www.serverurl.com/v2/{myServerVariable}",
variables = {@ServerVariable(name = "myServerVariable",
defaultValue = "Rachell")})}
)The ServerVariable annotation represents a server variable for server URL template substitution.
@ServerVariable(name = "myServerVariable",
enumeration = {"Tommy", "Rachel", "Jana"},
defaultValue = "Rachel",
description = "This is the ServerVariable."
)The Tag annotation represents a tag for the API endpoint.
@Tag(name = "MusicType",
description = "Operations related to selecting music",
externalDocs = @ExternalDocumentation(description = "This is the description",
url = "www.url.com")
)The Tags annotation creates a container of multiple tags.
@Tags(value = {@Tag(name = "MusicType"),
@Tag(name = "Artists")},
refs = {"#/components/schemas/Music0",
"#/components/schemas/Music1"}
)