Store API definitions in more than one file, enable linking
With just 4 api calls the file is already getting pretty big, I would welcome being able to organize the API blueprints into subdirectories somehow.
Also being able to identify an API call and link to it both from outside (as in: use THIS api call to do what ou wish) and inside (this api call is the same as THIS except for ...)
Undocumented pre-alpha is live, but not all in-product edges are fine-tuned properly.
Please let us know (e-mail to firstname.lastname@example.org) if you want to use this feature, we will give you a howto.
Troy Ponthieux commented
You guys really missed the mark with the architecture. Instead of storing the markup for multiple APIs in one big text blob, the different components of an API's documentation should be stored as columns in a database table. With so little discipline as far as what's allowed, no one on my team seems to be able to get it right.
AdminZ (Admin, apiary.io) commented
Note that in addition to current alpha implementation this suggestion might be covered by upcoming API Blueprint Format update. Please refer to http://support.apiary.io/forums/120125-general/suggestions/2970802-new-api-blueprint-format.
thanks for you interest; you both should have e-mail from me in your inbox.
I'm ready to give it a go, for sure. Looking forward to it!
Andrei Neculau commented
Almad, I'm in for some ratlab work.
good point again. This is planned as part of http://apiary.uservoice.com/forums/120125-general/suggestions/3066163-support-data-structures (with importing structures from other files, yes).
We'll keep you posted.
It would be really nice to be able to separate the expected response from the request definition and have it imported into the documentation. The api I'm working on needs some fairly large responses to be useful in testing the client as it's developed in parallel with the service and the responses are making it a real pita to move through the .apib
The Admin comment below links to this same page.
Manifest approach is a good point, we'll think about that.
I'm running into the same issue. I favor a manifest approach though, similar to what Rails 3.x uses for js assets, rather than requiring subdirectories. This might also play a role in testing of specific portions of the api against the host service as it's developed.
AdminApiary (Admin, apiary.io) commented
Actually there is another idea with the same content, please send all your votes here: