search

mulesoft / api-designer

A web editor for creating and sharing RAML API specifications
Other
1.07k stars 269 forks source link

Raml document decomposition #205

Open apomelov opened 10 years ago

apomelov commented 10 years ago

I'd like to decompose a large raml document, e.g. by top level resources. Everything works well but one thing. I can't tell editor, that the contents of some *.raml file is not a whole document but a single resource and I can start this file with http methods, but not title and version. Is it possible?

sichvoge commented 9 years ago

@apomelov, are you still on that? Would be great to understand more what you want to achieve.

apomelov commented 9 years ago

@sichvoge , hello. To be honest I'm not using API designer now. I understood it is very difficult for me to support actual specification the same time I develop new features:) But I'll try to describe my issue. May be it will be helpful for somebody else. The idea was to specify some context for each raml file to activate correct autocompletion. I can say, that "main.raml" has the "root context". So editor will propose to fill in the title, version and so on. Than I declare a resource /user and include there another file "user.raml". Now I need to declare another context -- "resource context" for "user.raml". In this file editor should propose me to add http methods as top-level elements. In fact, this context could be implicitly inferenced from usage of the file "user.raml". I'm not sure that "context" is good term for this case but I hope my idea was understood.

sichvoge commented 9 years ago

I guess I do get what you mean. Currently the API Designer only knows about one file and can't see what's around it (files included). You suggest that we should make the editor more "context" aware, so that the current "view/editor window" knows about all included files. Am I right?

robertlevy commented 9 years ago

big +1 on this. we choose RAML over alternatives because it lets us split stuff into lots of small reusable files. but api-designer currently isn't super useful unless you are only editing the 'main' RAML file. Date: Wed, 17 Jun 2015 11:47:36 -0700 From: notifications@github.com To: api-designer@noreply.github.com Subject: Re: [api-designer] Raml document decomposition (#205)

I guess I do get what you mean. Currently the API Designer only knows about one file and can't see what's around it (files included). You suggest that we should make the editor more "context" aware, so that the current "view/editor window" knows about all included files. Am I right?

— Reply to this email directly or view it on GitHub.

sichvoge commented 9 years ago

OK - seems to be really useful. To make a better justification for that, @robertlevy can I ask you to also provide some more context on the problem which such a feature would solve on your end and what "isn't really useful" means. It would help to better understand what needs to be implemented.

robertlevy commented 9 years ago

Over the course of a project we spend way more time tweaking these secondary files (especially schemas and examples) than the main RAML file.

Low hanging fruit would be to have the pretty documentation pane stay open and up to date while changing other files.

Even better would be having autocomplete account for traits/types/schemes defined in other files.

There may also be an opportunity to show smarter error messages but that work probably belongs in the parser rather than the designer

On Jun 17, 2015, at 5:37 PM, Christian Vogel notifications@github.com wrote:

OK - seems to be really useful. To make a better justification for that, @robertlevy can I ask you to also provide some more context on the problem which such a feature would solve on your end and what "isn't really useful" means. It would help to better understand what needs to be implemented.

— Reply to this email directly or view it on GitHub.

sichvoge commented 9 years ago

"Low hanging fruit would be to have the pretty documentation pane stay open and up to date while changing other files." +1 -> Definitely, especially editing markdown files. The console should also save state and stay at a view when you save a file. Currently, the api console automatically switch back to the list of resources.

"Even better would be having autocomplete account for traits/types/schemes defined in other files." BIG +1

Last but not least, yes - the error management is something we are looking at currently as well, but you are absolutely correct - it's not only the designer. ;)

BTW, if you want to help implementing the discussed topics - I would definitely not mind at all :) Let me know.