Support APIReponse on resource class

[Azquelt]

Scan for APIResponse annotations on resource classes and merge any
responses with those on the method.

APIResponse annotations on the method override APIResponse annotations
on the resource class with the same response code.

Implementation for eclipse/microprofile-open-api#524 I've opened this as a draft against the jakarta branch because it requires API updates planned for MP OpenAPI 3.1.

[phillip-kruger]

LGTM. @MikeEdgar please also have a look :)

[MikeEdgar]

I think this looks good also. This can target main once it's repurposed for the MP 3.1 milestone.

[Azquelt]

I've pushed another commit to support @APIResponse on exception mapper classes, as that requirement was added to the spec PR.

I had a question while writing this: what's your approach for handling when the user does something invalid or ambiguous? In this case it's possible to put @APIResponse on both the class and the method, or even to add the annotation multiple times in one place since it's repeatable. Should there be an error or warning if the user does this? How is this handled in the rest of the project?

[MikeEdgar]

I had a question while writing this: what's your approach for handling when the user does something invalid or ambiguous? In this case it's possible to put @APIResponse on both the class and the method, or even to add the annotation multiple times in one place since it's repeatable. Should there be an error or warning if the user does this? How is this handled in the rest of the project?

Typically in situations like that, one of the options is the one that is more "specific". Although in this case putting the annotation on the class is more in alignment with ExceptionMappers, I suppose the method is still "closer" to the result. Even in this situation, I think it's still valid for the mapper to return multiple status codes depending on the internal logic of toResponse.

[Azquelt]

I think it's still valid for the mapper to return multiple status codes depending on the internal logic of toResponse.

I hadn't considered that but I guess there's no reason an ExceptionMapper couldn't pick the response based on data from the exception. I'll try reworking this to process all annotations present on the class and method rather than just the first.

The base branch was changed.

[Azquelt]

I've rebased this on main and added a further commit to support multiple @APIResponse annotations on an exception mapper.

[MikeEdgar]

Thanks @Azquelt . Once the MP 3.1 snapshot includes this, we can double-check here that they pass before merging.

[MikeEdgar]

Here we would allow an exception mapper to override class-level responses, but not method responses. This makes sense I think 👍

[MikeEdgar]

Remove entirely?

[MikeEdgar]

New APIResponse TCK tests are passing. @Azquelt let me know when you're ready for this to merge. Just one thing to possibly look at with the commented code please. Thank you!

[MikeEdgar]

@Azquelt I think this may be good to merge as-is. Let me know if you're planning any other updates on this one.