feat: @Maturity annotation for endpoints

[jbee]

Summary

A new annotation that can be used in controllers to indicate the maturity of endpoints (methods) and/or individual endpoint parameters.

This is a first step for a long term goal for better documentation and the ability for the dev team to classify the API so that it is clear what conditions apply for users of the APIs.

For now the annotation is picked up by OpenAPI and rendered into the document as x-maturity. Such x- properties can be added to OpenAPI freely for additional information. It does not have any effect unless a tool specifically supports such additional properties.

Besides OpenAPI the maturity information might prove useful in other contexts.

[maikelarabori]

Nice initiative @jbee 👍
I just left some comments. Have a look if they make any sense.

Cheers

[david-mackessy]

Nice initiative Jan. I like the idea of bringing more clarity/intention to the APIs 👍
Do you think that the enum comments would be enough to circulate these changes with the wider community?

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

[amcgee]

This is a good initiative. I think EXPERIMENTAL, STABLE, and DEPRECATED could be a simple, easy-to-understand, and useful set of initial maturity states.

flowchart LR
   EXPERIMENTAL --> removed
   EXPERIMENTAL --> STABLE
   STABLE --> DEPRECATED
   DEPRECATED --> removed

Loading

[jbee]

@amcgee deprecated is a individual flag that already exists in form of @Deprecated and the OpenAPI standard and the annotations we have informed by it. We should discuss in what way we want to merge this information when presented to the user and if we want a DEPRECARED maturity classification value that is implied once something is deprecated or if the maturity stays STABLE.

[david-mackessy]

This text may be a bit misleading to some. It might not technically move to another Classification value but it could still move to Deprecated. This needs to be clear, whether that's in the code or the external publication or both. No harm mentioning it here I think.