- Notifications
You must be signed in to change notification settings - Fork 83
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 = "mycontact@email.com" )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" )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 = "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")) )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"} )