Uber RAML Support

[dirosden]

Hi,

When we use converters to generate RAML from the codebase (JAX-RS etc), it could be generated as micro-RAML, each individually providing specification for a resource. But from a packaging perspective, the need is for creating an Uber RAML that includes all of them to provide one single Product RAML. This makes writing Notebooks easier, since you dont have to reference hundreds of micro-RAML's in your client code.

The drawback we currently face are: a) The micro-RAML will have to be cleansed (remove the metadata and traits information individually in each of them) before they can be included into the Uber RAML; b) The micro-RAML have the actual Base URI where the API is listening. The Uber RAML Base URI, cannot be used unless its supported through some Proxy implementations. For simple RAML, Console and Notebook use cases, this is not an option. The "Try It" calls in such cases should be routed to the Base URI of the micro-RAML.

The asks are: a) Support Uber RAML to include clean micro-RAML, without modifications. The micro-RAML need to be valid, but need not be cleansed to be included in another; b) Support and use the micro-RAML baseURI, if present, for the actual "Try It" capabilities;

Regards, Venkatesh

[justjacksonn]

I am not entirely sure if this is what I am also needing, but RAML can currently support the ability to include other RAML files. The only problem is, there can only be one top level set of elements, such as Title, RAML version, etc. So, I have these "sub" RAML files that I include in one big one, so that the RAML2HTML module can create a single document of all my API surfaces (each in their own RAML file). It also makes it impossible for the designer to "code complete" because the sub-RAML files are not full RAML files..they lack the top level elements. It would be ideal if each and every RAML file could stand alone, but also be included in another RAML file that would "ignore" the top level elements (or in the !include.. if we could provide options..something like:

!include: { file: path, ignoreTopElements: true, somethingElse: false}

I have opened an issue around this: (https://github.com/raml-org/raml-spec/issues/140)

Thoughts?

[sichvoge]

IMHO, that is totally up to tooling. Its actually not that hard to write something that consolidates all RAMLs and builds an Uber RAML.

[brecko]

I am just getting started with raml and great job by the way on what you have done. Please pardon my navety of my question, but why would a uber raml file need to be created at documentation build time? Couldn't the tooling instead read the master raml file with the includes of other raml files and create the html file(s) from it OR gulp script that runs the tooling and creates individual html files with option to link them into a primary index.html file? I support the multiple raml files to match modularization of routes...Thanks!!

[sichvoge]

That in my opinion can be easily done with a script that takes a list of RAML files in and basically generates an Uber RAML or an HTML files, multiple HTML files, or what ever you like ;)

[marcoaltieri]

Given that the need to consolidate different raml files seems very common, wouldn't be better if the script to do it was part of the tools provided ?

[naghmeh48]

I was also hoping to find some free tools capable of consolidating/merging different raml files into one as many tools cannot read or import distributed raml files :( Any support is highly appreciated.

[twajjo]

+1, I have a project that has a number front ends that consume a mix of services. It would be great if each front end could stand up an OSprey mock service that had only the services the front-end consumes "included" into its master API raml file, with a different master RAML for each front end project.

In addition, a service on the backend would be able to validate itself against only its own RAML contract(s) rather than muddling it validation by having one big-ass RAML file with all contracts in it.

The RAML files themselves would be kept in a "contracts" git project that was independent from any front end consumer or backend provider of a service. Front-end and backend projects would then mount the contracts project as a submodule for standing up mock services on the front end and validating contracts on the backend.

Thanks, eagerly awaiting this sort of extension as it will save us a lot of headaches.