I can see how that would be hard to represent in RAML. You could go the path of defining a schema which is a superset of both possible responses - ?showAllDescendants=true and =false, but that won’t help you on the example front. To me, this feels like it’s a bit of an anti-pattern.
One design solution is to use custom media types in order to differentiate the single-level entities and the full-depth entities. In RAML, this would allow you to define that on a single resource/method, it will behave differently depending on the media type submitted/requested - essentially, the media type replaces the query parameter, and a client can always inspect the media type in a response to understand if it is receiving the single-level or full-depth resource. You can then document requests and responses independently for each media type, within that same resource. I should mention that fine-grained media type usage like this is hotly debated within the HATEOAS community, so you should do some reading to get different sides of the argument, and YMMV.
I should mention that we’ve discussed adding the ability to include multiple examples for a method, and I expect that will happen in the not too distant future. We’ve also discussed input-response mapping, but it gets complex really quickly. It’s certainly desirable, but we haven’t found a good approach yet. If you have any suggestions around this, I’m sure @usarid and the rest of the workgroup would love to hear them.
Hope that helps!