Add annotation examples to the Javadoc

[lauracowen]

This wiki page provides a set of useful annotation examples, but that information would be more useful to the developer at development time if it were available in the Javadoc. For example, the @CallbackOperation annotation's Javadoc would be a lot clearer and easier to follow if the example shown on the wiki page were provided in the section of the Javadoc that currently just says "Describes a single API callback operation.":

---

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

This could be done for all of the annotations' Javadoc.

[lauracowen]

Possibly also provide the output examples from here too, so the developer can see what the output is for the annotations they provide? https://github.com/eclipse/microprofile-open-api/wiki/Static-File-Samples

[arthurdm]

Thanks @lauracowen - this sounds like a good idea to me.

[arthurdm]

We agreed to do this in today's hangout.