Allow retrieving json description of API from http

mashery / iodocs

Interactive API documentation system

MIT License

1.89k stars 415 forks source link

Allow retrieving json description of API from http #39

Closed gggeek closed 10 years ago

gggeek commented 12 years ago

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

cstrzadala commented 12 years ago

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.

BlakeGardner commented 12 years ago

gggeek commented 12 years ago

@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)...

mansilladev commented 12 years ago

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?

dgcgh commented 12 years ago

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.

challgren commented 12 years ago

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

BlakeGardner commented 11 years ago

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

https://github.com/wordnik/swagger-core/issues/70

funmachine commented 11 years ago

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.

phairow commented 10 years ago

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!