Use Open API interfaces for REST endpoints

[dgroup]

Summary

Key	Value
Rule	UseOpenApiInRestEndpoints
Ruleset	io/github/dgroup/arch4u/pmd/arch4u-ruleset.xml
Category	Design
Framework	org.openapitools:openapi-generator
Since	0.1.0
Incidents in past at my experience	10+

Why?

Do we like it or not the REST API is a de-facto standard for API development and mostly a huge number of apps have it.
As soon as the app went go-live the API documentation for consumers will become one of the first questions.
There might be different ways how to produce the documentation for REST API, but the current rule is oriented on approach then REST endpoints are implementing Java interface (with methods that has annotations with endpoint details) generated by org.openapitools:openapi-generator:

@RestController
public class MyTypicalRestController implements TypicalRestApiGeneratedByOpenApi {
   @Override
   public String get() {
      return null;
   }
}

so,

1. It's not allowed to have public methods in REST controllers without @Override annotation.
2. Swagger annotations support is planned, not implemented so far