Vert.x Web RAML support

[Jotschi]

I have not found any open Issue that covers this Idea. I would love to see native vert.x web RAML support in a future version.

I'm aware that this may not be easy to add since all vert.x routes are not very declarative and request parameters are processed within the handler code.

I'm currently writing my own Vert.x RAML generator which assumes that the routes are not changing during runtime. I created a wrapper class Endpoint which wraps the Route object. This way I can access the http methods, paths etc after I setup my routes in order to generate the RAML resources.

    Endpoint readEndpoint = createEndpoint();
        readEndpoint.path("/:uuid");
        readEndpoint.description("Read the user with the given uuid");
        readEndpoint.method(GET);
            readEndpoint.displayName("User");
        readEndpoint.exampleRequest(new GenericMessageResponse("test"));
        readEndpoint.exampleResponse(200, responseExample);
        readEndpoint.produces(APPLICATION_JSON);
        readEndpoint.handler(rc -> {
            InternalActionContext ac = InternalActionContext.create(rc);
            String uuid = ac.getParameter("uuid");
            crudHandler.handleRead(ac, uuid);
        });

[Jotschi]

This issue is also related to #138. It would be really helpful to traverse the route mounts in order to build the absolute path for each route/endpoint.

[Jotschi]

For anyone interested. I created a small prove of concept which illustrates how i'm currently generating my RAML: https://github.com/Jotschi/vertx-web-raml/

[pmlopes]

I think we could try to unify the PoC with https://github.com/pmlopes/yoke/blob/develop/examples/swagger-petstore/src/main/java/com/jetdrone/vertx/extras/SwaggerExample.groovy and have a a couple of handlers to produce the basic RAML and SWAGGER documentation json files.

[Jotschi]

Do you also suggest to create a dedicated wrapper similar to the com.jetdrone.vertx.yoke.middleware.Swagger or should the vertx web router be able to handle route descriptions using json? (e.g.: Route#addModel, Router#setInfo)

[pmlopes]

That old code was just to show that we can support also swagger in a similar way. By no means I am saying that it should be like that since that was built for yoke not vertx web.

[Jotschi]

I see.. Describing the route using information from a JsonObject is interesting. Storing arbitrary data next to the route open's up many possibilities. But I think dedicated methods to set needed information to generate RAML/Swagger are preferable because the code for the route would look cleaner.

@pmlopes You are currently planing to refactor the route code. Do you think it would be a good idea to include such methods? (e.g.: Route#description, Route#exampleResponse ...)

A side note. It would help a lot if it would be possible to traverse all routes and nested routes / sub routes of a router.

[pmlopes]

@Jotschi I don't think the new methods should be added to the router but to an api handler that wraps the router, in a way like in your poc. The idea is that api documentation is a different concern than routing so they should be keep apart WDYT?

[Jotschi]

@pmlopes Sounds good. Splitting the concerns makes totally sense to me. I'll give it a try and rework the PoC I did. I'll post an update here so you can take a look at it.

[Jotschi]

@pmlopes I have updated my poc and added a wrapper for the vertx router as well. A typical example would now look like this:

    RestRouter restRouter = RestRouter.router(vertx);
    RestRoute readOne = restRouter.route();
        readOne.path("/:userUuid");
        readOne.description("Read the user with the given uuid");
        readOne.uriParameter("userUuid", "Uuid of the user.", "2f2de9297c8143e8ade9297c8193e8fc");
        readOne.method(GET);
        readOne.produces("application/json");
        readOne.exampleResponse(200, getUserResponse());
        readOne.queryParameters(DummyParameter.class);
        readOne.handler(rc -> {
            rc.response().end(getUserResponse().toString());
        });

There is still a lot to do and I also needed to change a few bits and pieces in vertx-web in order to expose needed information about routes. There are a few RAML specific methods in my poc which would need to be replace with more generic ones and I have not yet worked on a RAML handler as well. Anyhow.. I think the code should give you an idea how I imagine the wrapper to work.

https://github.com/Jotschi/vertx-web-raml/tree/rework/src/main/java/com/gentics/vertx/raml

[Jotschi]

Needed Vert.x web changes: https://github.com/vert-x3/vertx-web/compare/master...Jotschi:f-route-raml-enhancements

[Jotschi]

The raml-java-parser v2 does currently not provide any RamlEmitter. Thus it is currently not possible to generate RAML the same way as I did it within my PoC. The emitter would be needed to generate RAML 1.0 documents. Related Issue: https://github.com/raml-org/raml-java-parser/issues/159

[pratikpparikh]

@Jotschi I see that we now have an emitter as part of https://github.com/mulesoft-labs/raml-java-tools, can the progress be made here?

[Jotschi]

@pratikpparikh Looks promising. I'm thinking about writing an additional/extended router / routes implementation which could support this. I'll take a look at this once my backlog allows it.

[pratikpparikh]

@Jotschi Thank you. So the plan is to support both RAML and swagger production based on extended router routes. Just wanted to understand and was wondering what you were thinking.

[Jotschi]

@pratikpparikh I have not yet worked with Swagger/OpenAPI so I can't say much about it but I have an enhancement issue open for OpenAPI as well: https://github.com/gentics/mesh/issues/188

For Gentics Mesh I would love to support RAML and OpenAPI.

[pratikpparikh]

@Jotschi since you are aware of what you need to do with RAML support, I am not an expert on either but i can try to pitch in to help add swagger support when you are done with RAML side of the equation.

[pmlopes]

@pratikpparikh we already have support for swagger http://vertx.io/docs/vertx-web-api-contract/java/

[Jotschi]

@pmlopes That approach requires a spec upfront (Design Driven). The other approach is to generate the spec from existing code.

[pmlopes]

Currently we don't support spec from source, and it's not on the current scope, perhaps this could be a community project.

Will close for inactivity.

[Jotschi]

@pmlopes I also believe that OpenAPI has a wider acceptance by now.