We have been using the API Designer and have run into it reaching the point of ‘painful’ when editing our current raml file.
As it stands, our file is 1000+ lines and referencing 170+ json files (albeit small files). We plan on adding much more to it before it’s finished but it’s a bit of a slog currently.
An option to include on demand parsing instead of continuous parsing might help.
Is there any way you can break it up into several files… and refer to those raml files from another? Not sure if that would affect the final documentation or not either. But perhaps if you have just a single top level entry point, with resources below it, you could move those top level resources (below the top entry point) into separate raml files, then, perhaps if there is no way to refer/include them in the main “outer” raml file such that documentation, code gen, etc works, have as part of a build process a concatenation of all raml files into one big one, then run parsing/doc gen/code gen on the one big one?
Seems raml should allow for “modules”. I’d even say the API Designer (and any IDE plugins) should allow for some sort of expand/collapse of specific resource paths, and a collapse-all/expand-all feature as well, so you can work on a specific resource or sub-resource area without having to possibly scroll down 800 lines or however far in to the file you are working at. IT would also allow separate groups of people to work on individual raml files, with the knowledge that the entire thing will be put together during build time.
Is there any way you can break it up into several files… and refer to those raml files from another?
Yes the include word can be used for that
#%RAML 0.8
title: "Financial API"
baseUri: https://api1.site.com/test/{version}
version: 1
documentation:
- title: Description
content: !include http://xxx.xx.xxx.xxx/finAPI/docs/description.md
/exchange:
description: Obtain the coverage to exchange risk
displayName: Exchange
get:
description: This service obtain the value of money in exchange currency
queryParameters:
type:
description: type of change (spot or forward)
type: string
example: ask
displayName: type
default: ask
amount:
description: import to buy or sell
type: number
example: 500000
displayName: amount
currency_from:
description: currency source
type: string
example: EUR
displayName: currency_from
currency_to:
description: currency destiny
type: string
example: USD
displayName: currency_to
responses:
200:
body:
application/json:
example: !include http://xxx.xx.xx.xxx/financialAPI/examples/exchange/get_200.json
schema: !include http://xxx.xxx.xx.xx/financialAPI/schemas/exchange/get_200.json
Just be carefull when using relative paths, we preffered absolute paths for URLS and relative paths when using filepaths (LocalStorage or local file system).
In the biggest API we are using with a couple dozens JSON and XML and MD (for doc) has like 25 endpoints with several methods on each… and yes, the API Designer gets slower and slower since it tries to render the API Console (on the right) parse all the includes to verify its a valid RAML file.
I will adventure and say that you edit your RAML in text editor (or sublime with raml plugin) and then try to parse your files with the raml parser (pythong o javascript)… on the command line interface. Other than that just divide and conquer into smaller APIs Spec Files which is the obvious solution.
The API Designer developers should take a look at using ReactJS… would probably greatly speed up the UI rendering.
Hi guys, thanks for bringing that up. We will definitely take a look at that and since we got not that far to have such large files, @darrenf_gillis are you able to send us your example so we can use it to do some performance testing and therefore improvements as well? Or is someone else able to share us something?
Any update on the status of this? I am curious… does the RAML editor (which I believe is written with AngularJS?) validate the RAML file on every keystroke? Is it using the RamlJS module (available separately) within the editor to validate the edited document? Just wondering if that may be one of the reasons larger documents start slowing things down and if there is some way to offload that to say a server (via async task with only the edited “diff” going to the server), or perhaps a background task (if possible) in JS to validate the file?
@justjacksonn Currently everyone is extremely busy which doesn’t leave a lot of time to this, but I do want to improve it as soon as possible. The parsing is actually throttled, but there are definitely improvements for the speed we can look into (web workers, cache multiple file results, etc). We’re using the RAML JS Parser for validation and parsing.
Hi and thank you for your reply. I am replying a bit late to this myself due to being busy, so I definitely understand. I do draw a little concern however at what you’ve said…I assume there is probably a team of developers at Mulesoft dedicated to RAML… is that not the case? Given that RAML is being adopted by larger companies and many smaller ones, I would hope that there is a team at Mulesoft working on RAML, spec, tooling, etc full time? It would be a shame given the breadth of this project and the number of companies adopting it that they would publish this and then not contribute to it on a regular basis. Not trying to be mean, just hoping that I’ve made the right choice in going with RAML under the assumption that there is a fast growing community around adding new tools, fixing/improving the existing ones, etc?
Hello Justin,
Thanks for posting your concerns.
I recently joined MuleSoft to work full-time in RAML. We’re doing a lot of work around the spec.
We are integrating RAML with tools that run on desktop, server and IDEs. Customers are using RAML to build small APIs as well as describe large collections of existing, Twitter-sized APIs. There are a bunch of new projects in the pipeline.
At this point we’re prioritizing getting RAML 1.0 nailed down. One of the differences between RAML and the other “API Description Languages” is that RAML has been, from the onset, a “Modeling” language. We not only provide the basic “HTTP Interface elements”, but we extend this set with higher level constructs ( Resource Types and Traits ) to support capturing and reusing patterns. This has proven to be very valuable and we want to be sure we understand the good parts and the bad parts now that people have been using them for a while. This added complexity also means that we have to pay an extra overhead when it comes to building tools and that we need to be sure we understand all corner cases ( see the debate around !includes within resource type and traits ).
As for the present. The current RAML tooling is being worked on constantly ( see the commit logs ). We use these projects internally and they are part of MuleSoft products. This is both good and bad. It is good because it means that you can be sure these projects will continue improving at a constant and predictable rate with high quality standards, but sometimes this higher bar for quality slows things down a bit. It is probably easy to fix one specific issue in isolation, but we have to weight it against how it impacts the same project running in other platforms, how it interacts with other new features etc. We’re working on making this process a bit faster.
Thanks!
A
Hi, referring back to my post and in reply to Lulx back in Oct of last year… I am running in to an issue with the jax-rs module when including xsd and json schema. I am running the build locally using their example java code to initiate the jax-rs generation. It works in that the raml file itself generates the source code. However, the includes are failing to find the schema files. I have a resource directory, let’s call it resource. In it I have test.raml and schemas/test.xsd. In my raml file I have at the top of the raml file:
schemas:
Further down I refer to it in the body of a resource:
get:
description: test
body:
application/xml:
schema: test
It works in the API Designer…the help system shows the schema source. But when I try to get the jax-rs to generate the pojos (models), it can’t find the xsd.
I may be missing something, but the documentation is severely lacking on how to configure the use of say gson over jackson, as is any information on how to configure paths in the raml file to schemas. Does anyone have this working and can shed some light on the proper way to declare the schema locations outside of direct http:// locations? There should be some way to specify relative paths from the location of the raml file itself.
Thank you.
Hi @justjacksonn - can you create an issue on the Github repository for this project please. It is then easier to track for the developers.
