Migration path: separation of HTTP API definition from implementation

[mrwilby]

Issue description

We are migrating from 1.x to 3.6.x.

In our system, we define our HTTP API specifications via java interfaces. All swagger annotations and generic API semantics are declared in a java module that only contains java interfaces, annotated with swagger, micronaut server-side and jakarta annotations (e.g. Nullable, Non/NotNull etc). We need to use the validation rules/etc in the API interface so that the swagger processor understands required vs optional and therefore produces the correct swagger definitions.

We then implement the actual interfaces inside a separate micronaut http server-side modules (e.g. using netty, or AWS API gateway, depending on the deployment scenario).

We have declared some optional HTTP request parameters (e.g. query) in our API interface module. As mentioned above, we do this e.g. via @nullable so that the swagger file correctly reflects the optionality.

In 1.x, the server-side HTTP interface implementation also was correctly aware of the optionality. However, in 3.6.x our tests fail because the server module appears to be unaware of the Nullable annotation that was applied to the java interface definition.

From reading https://docs.micronaut.io/3.6.0/guide/#breaks it appears that this is intentional:

Annotation Inheritance

Possibly the most important change in Micronaut 3.0 is how annotations are inherited from parent classes, methods and interfaces.

Micronaut 2.x did not respect the rules defined in the [AnnotatedElement](https://docs.oracle.com/javase/8/docs/api/java/lang/reflect/AnnotatedElement.html), and inherited all annotations from parent interfaces and types regardless of the presence of the [Inherited](https://docs.oracle.com/javase/8/docs/api/java/lang/annotation/Inherited.html) annotation.

With Micronaut 3.x and above only annotations that are explicitly meta-annotated with [Inherited](https://docs.oracle.com/javase/8/docs/api/java/lang/annotation/Inherited.html) are now inherited from parent classes and interfaces. This applies to types in the case where one extends another, and methods in the case where one overrides another.

The consequence of this is that we now need to apply @nullable annotations on both our API interfaces and also implementations, which is clearly error prone and not consistent with the principles of DRY.

Our biggest concern is that in order to make the APIs work again, we will need to copy & paste the annotations. There could be some human error during this exercise, which might lead to an endpoint behaving incorrectly. Hopefully test coverage would prevent this, but there is always a risk that we missed a test case.

What is the recommended approach to such migrations?

[graemerocher]

you can define your own Nullable annotation that is meta annotated with @Inherited

[mrwilby]

@graemerocher thanks, so you suggest subclassing the suite of e.g. Jakarta annotations and adding @inherited to each subclass, then using those new subclassed annotations instead?