Skip to content

Annotation Samples

Jump to bottom
Arthur De Magalhaes edited this page Jun 1, 2018 · 2 revisions

MP OpenAPI 1.0 Annotations

Callback Sample

The Callback annotation represents a callback URL that will be invoked.

@Callback(name = "myCallback",
	callBackUrlExpression = "www.myurl.com",
	callBackOperation = { @CallBackOperation(method = "POST")}
)

Callbacks Sample

The Callbacks annotation represents an array of Callback URLs that can be invoked.

@Callbacks( value = {@Callback(name = "myCallback")})

CallbackOperation Sample

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"
	)}
)

Components Sample

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")}
)

Extension Sample

The Extension annotation adds an extension with contained properties.

@Extension( name = "x-header",
	value = "The extension value"
)

Extensions Sample

The Extensions annotation adds custom properties to an extension.

@Extensions(extensions = {@Extension( name = "x-header",
	value = "The extension value")}
)

ExternalDocumentation Sample

The ExternalDocumentation annotation references an external resource for extended documentation.

@ExternalDocumentation(  description = "A short description of the target documentation.",
	url = "www.urlfortargetdocumentation.com"
)

Header Sample

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
)

Contact Sample

The Contact annotation describes the contact information for the exposed API.

@Contact(name = "The name of the contact",
	url = "www.urlofcontact.com",
	email = "mycontact@email.com"
)

Info Sample

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 = "mycontact@email.com"
	),
	license = @License(name = "The license name used for the API."),
	version = "application version number"
)

License Sample

The License annotation describes the license information for the exposed API.

@License(name = "The license name used for the API.",
	url = "www.myurlformylicense.com"
)

Link Sample

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")}
	)
)

LinkParameter Sample

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"
)

Content Sample

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")
)

DiscriminatorMapping Sample

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")
)

Encoding Sample

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")}
)

ExampleObject Sample

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",
)

Schema Sample

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
)

OpenAPIDefinition Sample

The OpenAPIDefinition annotation provides general metadata for an OpenAPI definition.

@OpenAPIDefinition(info = @Info(title = "Music Title",
	contact = @Contact(name = "Mr. X",
		email = "mrxyzufo@xxx.com"),
	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"))
)

Operation Sample

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
)

Parameter Sample

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"
)

Parameters Sample

The Parameters annotation encapsulates input parameters.

@Parameters(value = {@Parameter(name = "music albums"),
	@Parameter(name = "Artists")}
)

RequestBody Sample

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,
)

APIResponse Sample

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"
)

APIResponses Sample

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")}
)

OAuthFlow Sample

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")
)

OAuthFlows Sample

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"))
)

OAuthScope Sample

The OAuthScope annotation represents an OAuth scope.

@OAuthScope(name = "read:reviews",
	description = "read a review"
)

SecurityRequirement Sample

The SecurityRequirement annotation specifies a security requirement for an operation.

@SecurityRequirement(name = "ouath2",
	scopes = "read:reviews"
)

SecurityRequirements Sample

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")}
)

SecurityRequirementsSet Sample

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")}
)

SecurityScheme Sample

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")))
)

SecuritySchemes Sample

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")}
)

Server Sample

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")}
)

Servers Sample

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")})}
)

ServerVariable Sample

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."
)

Tag Sample

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")
)

Tags Sample

The Tags annotation creates a container of multiple tags.

@Tags(value = {@Tag(name = "MusicType"),
	@Tag(name = "Artists")},
	refs = {"#/components/schemas/Music0",
		"#/components/schemas/Music1"}
)
Clone this wiki locally