I use ControllerLinkBuilder to create an index of links pointing to a list of Spring MVC controllers.
For example:
ResourceSupport resource = new ResourceSupport(); resource.add(linkTo(methodOn(ReactorController.class).sendmail(EventBody)).withRel(REACTOR_REL));
This generates:
"reactor": [ { "href": "http://localhost:12345/main/reactor/sendmail" } ]
In the example it is a POST to sendmail that is expected! What is the way to document that a POST is expected ?
When you provide a link, you are pointing to a resource which can be manipulated by the users of your API, not a function they are expected to know how to use.
https://spring.io/understanding/HATEOAS
The last segment applies to your question.
According to the Richardson Maturity Model, HATEOAS is considered the final level of REST. This means that each link is presumed to implement the standard REST verbs of GET, POST, PUT, and DELETE (or a subset). Thus providing the links as shown above gives the client the information they need to navigate the service.
So in your case, if it does not make sense to implement any of the methods but post, you can just let them post to /mail and you may create a separate documentation (like Swagger, Spring REST Docs) to let them know your format of entity.
