Allow retrieving json description of API from http #39

gggeek opened this Issue Aug 26, 2012 · 9 comments

8 participants


It makes a lot of sense to get the whateverapp.json from http and not only from local filesystem. This way there's no need to copy it locally on every update


This is a great idea. Swagger UI allows this and makes it easier to deploy the json for api doc changes separately then the whole IO Doc application with new json api details.


@cstrzadala Thanks for the pointer - I did not know about Swagger. From a quick glance at the docs, it seems to use a different format for API description than IODocs. Could you point me to a page describing the pros and cons and differences between the two? It sure would be nice to have a single, universal standard for this, a la WSDL (without the huge complexity of course)...


gggeek - is it safe to say that you're suggesting rs.readFile* operations be replaced with http reads if the URI is a URL and not a local file? Interested in forking / prototyping and we can gauge interest and community rev on it?


I've been interested in the RESTful WSDL equivalent for a while now, and I'm currently working on adopting json-schema and the iodocs config format to that purpose internally.

Also, re: OP, I think that's a great idea, and pretty easy to implement.


Great idea OP! I may have to learn node now!


There is a discussion going on right now about this same issue with swagger UI.



I implemented a very simple solution for this in our fork, along with a couple of other goodies: funmachine/iodocs. Basically it will load the API definition from a URL instead of a file if the 'apiDefURL' key is provided in the api configuration. It loads at page view time so documentation stays current as you edit the source at the remote location. Relies on the restler module since I used that in another big feature (file upload field types) and it made the code a lot slimmer.

Note that our starting point was the jasonmccreary/iodocs fork, so it would require a little effort to merge this cleanly.


thanks to @rowanhill this was added in #137 and the directory which to serve definitions is configurable using the config file -

"apiConfigDir" : "./public/data/"

Nice work!

@phairow phairow closed this Oct 10, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment