You guys are hitting on exactly what RAML CAN do.. but is not yet quite capable of. Let me explain my vision.. at least what I know is possible but not yet implemented. The beauty of RAML 1.0 besides the RAML Types (which has the potential to replace JSON Schema in my opinion), is the annotation framework. The unfortunate problem of the annotation concept with RAML is that it is completely left to each and every RAML parser/generator to implement.. and as such is difficult at best to say USE THIS because you dont know who is going to support your dynamic annotations. You can certainly provide robust documentation by using Markdown and including links to it in your RAML... but let me jump to my biggest problem with Swagger UI and RAML2HTML. They both merely show you a list of endpoints and what each does.. in their own respective layouts. I personally dislike Swagger UI.. it lists every endpoint in a flat list of endpoints that you can expand, try, etc. Same with RAML2HTML but it is more organized by grouping the GET/PUT/POST/etc into a tree structure. Still.. you have NO IDEA how to use the API just by looking at it. It is merely a way to understand a specific endpoint. You can try any endpoint..but some endpoints require data as part of the request.. how do you know what API to call to get the data needed? That information is lacking in current API designs.
So.. that is where annotations come in to play for me. It would not be difficult to define a few annotations that indicate WHAT API endpoint must be called BEFORE this endpoint can be called.. and WHAT response data from that call must be available before this request can be called. With that data information, you can actually auto generate Postman collections, complete automated tests, etc. It is completely possible to do this today with RAML 1.0 (but not Swagger or RAML 0.8.. or at least without a huge amount of work and secondary files). The only thing holding this back.. what tool utilizes the defined annotations to provide this info? If RAML2HTML is the defacto standard way we generate API documentation from RAML, and RAML2JAXRS is the defacto way we generate JAXRS server side code from RAML.. how will they take advantage of these new custom annotations to generate better documentation, code, etc? There inlies the problem. They wont. Or at least.. they probably wont. You have to get EVERY project/team/developer on board with a set of "standard like" annotations that they all agree to, or at least agree to providing support for those annotations.
The question has been raised before..why are there not a set of annotations the RAML 1.0 spec defines and requires support of? I have asked that too. I think the main reason is... the spec is beyond good enough to define API endpoints, in fantastic detail.. enough that you can provide good API endpoint documentation, good code generators to build SDKs, CLIs, etc with. BUT.. there is NO WAY the SPEC designers could possibly know how any given API will be used, so I think the choice to leave annotations as a custom option makes good sense.
To that end, what I have pitched to @christian_vogel and he has told me to figure something out (so maybe this is a good way to lead in to that) is to put together some sort of central set of annotations that we as a group define.. not only writing the actual .raml file with them defined, but documentation on what they mean, how they should be used, etc. I have proposed the idea on the RAML.org site that we have a menu option or something that says Annotations or whatever, and on that page, we define/list them, and as well, list the different projects that support custom annotations. Id also like to see individual projects have something show up on that say Annotations support (a link) and a popup/etc of the annotations it supports. I think it is a very good step towards what the OP and myself and others would like to see.. how to define a way in the RAML API definition of using the API endpoints.
The biggest problem with the above approach will be projects supporting different annotations. So now, if RAML2HTML only supports say a couple, but not all.. then we need yet another doc generator tool to add support for the rest.. but then you are using 2 tools or 3 or 4 to get your docs generated with all the support you want.. or we are having multiple different doc generators, each with their own way of generating doc layout/details.. so now someone may love RAML2HTML output, and not like the other format.. but wants the annotation support the other format has.
Hopefully what this will foster is more developers in the community joining up to add support for annotations (assuming we get that in place first) for given projects!!
So.. lot to say.. what do you think?