Make the list of annotations in the spec more useful

[Azquelt]

Currently, the spec lists all the annotations defined by the api: https://download.eclipse.org/microprofile/microprofile-open-api-3.1.1/microprofile-openapi-spec-3.1.1.html#_quick_overview_of_annotations

This list includes annotations which are only used within other annotations (e.g. @ServerVariable) as well as annotations whose only purpose is to be the @Repeatable container for another annotation (e.g. @Callbacks).

Given that the API documentation already includes the full list of annotations, I'm not sure what value this list serves.

I think it would be more helpful to list annotations by where they can be applied. E.g. a list of annotations which can be placed on a resource method or class to customize an operation and a list of annotations which can be placed on an application or resource class to customize the metadata for the whole application.

This would give users a starting point to discover the annotations they might need to use.

[Azquelt]

We agree we

• should not list the container annotations
• should not list annotations that can only appear as children of other annotations (i.e. target is {})

This would be a fairly small piece of work.

I'd still like to define which annotations can be used where and what they mean in those locations, but that's a much larger piece of work and we'd also need to ensure that we have tests for everything we define.