Clarify RouteToEBServiceHandler Documentation

[lukasalexanderweber]

Describe the feature

we might want to

• link routeToEventBus Javadoc to RouteToEBServiceHandler Javadoc make clear it uses it under the hood (optional)
• In RouteToEBServiceHandler Javadoc, we might want to replace the missleading

The HTTP request is sent encapsulated into a ServiceRequest object through the event bus. The expected reply is a ServiceResponse

We should make clear that not a ServiceRequest object is send through the event bus, but its JSON representation (JsonObject derived by #toJson). The ServiceResponse is also expected to be in its JSON representation (see the use case below).

• The RouteToEBServiceHandler Implementation still uses (the depreciated?) OperationRequest instead of ServiceRequest

Use cases

I start my "OpenAPIRestVerticle" like this

  public void start(Promise<Void> startPromise)
  {
    String openapiFile = config().getString("openapi.file");
    RouterBuilder.create(vertx, openapiFile).onSuccess(routerBuilder -> {
      for (Operation operation : routerBuilder.operations())
      {
        operation.routeToEventBus("api." + operation.getOperationId());
      }
      Router generated = routerBuilder.createRouter();
      Router.router(vertx).route("/api/*").subRouter(generated);
    });
  }

while my Web API Service listening as

    // Map<String, Method> methods with a method for each action
    for (String openapiId : methods.keySet())
    {
      vertx.eventBus().consumer("api." + openapiId, msg -> {
        execute(msg);
      });
    }

Since the docs state

The expected reply is a ServiceResponse

I tried to return a ServiceResponse

  public void execute(Message<?> msg)
  {
    ServiceResponse op = ServiceResponse.completedWithJson(new JsonObject());
    msg.reply(op);
  }

but got a No message codec for type: class io.vertx.ext.web.api.service.ServiceResponse error. I was tempted to implement such a message codec and it took me too long to realize (looking into RouteToEBServiceHandler) I can just return the ServiceResponse#toJson

  public void execute(Message<?> msg)
  {
    ServiceResponse op = ServiceResponse.completedWithJson(new JsonObject());
    msg.reply(op.toJson());
  }

Contribution

I could work on that if the upper makes sense to you