Factoring for microservices?


There have other topics asking about includes at the resource level

/resourceA: !include resourceA.raml
/resourceB: !include resourceB.raml

But this has been “not recommended”.

How is it then envisioned to define a single API that is build from many microservices, each with its own resource root?

Where each microservice desires to use something like osprey to front its express handlers?
Where each microservice may have its own version number distinct from other resource roots?
Where it is desired to use something like api-console to host the unified API documentation and support 'try it"?


What I would do is write a small script that builds you your an “Uber RAML” based on some configuration for what smaller RAMLs you want to combine. That can easily be run in a CD / CI process.

The above approach might not be recommended, but not invalid. You can still do it, but resourceA.raml and resourceB.raml is only a fraction of a RAML not a RAML. The differences is that you might not get validation.