Make REST API documentation easier to use using Swagger

[ceefour]

Make REST API easier to use using Swagger.

Can be accessed at:

• http://127.0.0.1:5000/api/v1.1/spec.html for human-friendly UI
• http://127.0.0.1:5000/api/v1.1/spec.json for JSON descriptor

Additional dependency is needed in opencog/python/web/api/install_dependencies.sh :

pip install flask-restful-swagger

@cosmoharrigan I hope this is acceptable. Thanks! :)

Fixed #927.

[cosmoharrigan]

@ceefour The example screenshot looks nice. Swagger is a nice feature. Is it your impression that flask-restful-swagger is a stable project?

Does this unit test pass in Nose after these changes?
https://github.com/opencog/opencog/blob/master/tests/python/test_restapi.py

[ceefour]

How do I run the unit tests?

https://github.com/rantav/flask-restful-swagger is being actively developed. However, Swagger itself has a large and vibrant ecosystem. The Swagger tools (spec, JSON, web UI in JavaScript) are cross-language and not Python-specific. Meaning, for example, OpenCog's REST API's spec.json is directly consumable by Java and .NET versions of Swagger libraries.

[cosmoharrigan]

Indeed, I have seen Swagger before, and it looks nice.
To run the unit tests, use nose: https://nose.readthedocs.org/en/latest/
Thanks!

[ceefour]

Here it is:

ceefour@hendy:~/git/opencog/tests/python > nosetests test_restapi.py 
..............
----------------------------------------------------------------------
Ran 14 tests in 0.147s

OK

[cosmoharrigan]

@ceefour Thanks. I think this is a nice change, providing usable API documentation. I believe the additional dependency on flask-restful-swagger is probably alright, since it already depends on Flask and flask-restful.

If possible, please see if there is any useful information included on the wiki page here:
http://wiki.opencog.org/w/REST_API
that is not already part of this documentation, and include it; also, how would you suggest making the Swagger API documentation available to interested parties who don't already have the REST API running?

@sebastianruder you will need this additional dependency, since you're consuming the REST API. @githart please note the additional dependency introduced here that will be necessary for the REST API unit testing to continue to occur on the continuous integration server.

[ceefour]

Thanks @cosmoharrigan :)

Here's it: http://wiki.opencog.org/w/REST_API#Swagger_Documentation

OpenCog REST API comes with built-in user-friendly API documentation powered by Swagger.
In addition to browsing documentation for each endpoint easily, you can also play
with the API directly without any coding by filling parameters using the dynamic AJAX UI.

Known Issue: For POST/PUT endpoints, to make documentation easier to read
each parameter is listed as form, however in reality they're part
of the JSON body's schema. So currently the "Test It Now" functionality of those
endpoints don't work as intended. To fix it then either we should make the endpoints
understand form parameters as well as JSON, or fix the Swagger annotations to include
proper Model schema.

To make it available to the "outside world", all you have to do is get the dynamically generated spec.json file and put it somewhere on a webserver. To view it as HTML, you need Swagger UI which a client-side JavaScript "app". It's bundled with flask-restful-swagger but it's actually part of Swagger project: https://github.com/wordnik/swagger-ui so you can put that in your webserver as well.
Of course users won't be able to play with the API directly because there's not a live server but at least they can browse documentation.

BTW, I believe you can use GitHub Pages to host this, it can be in the opencog project so making the public OpenCog REST API documentation always in sync with the development progress. I think that's a win :)

Thanks @rantav for making this possible :)

[cosmoharrigan]

@ceefour it would be nice to replace the wiki page documentation with the dynamically generated documentation, at some point, to avoid redundancy and to expose a more user-friendly version.

[ceefour]

@cosmoharrigan Here it is: http://ceefour.github.io/opencog/

I can't pull request on a new branch, so you need to clone the gh-pages yourself from https://github.com/ceefour/opencog/tree/gh-pages

Let me know if it works for you.

[cosmoharrigan]

@ceefour thanks, that looks good; can you please fork this repository:
https://github.com/opencog/rest-api-documentation
and then apply your changes to it and create a pull request, rather than applying the changes to the opencog repository as it is currently presented?

[cosmoharrigan]

@githart I created the repository https://github.com/opencog/rest-api-documentation to contain the Swagger interactive REST API documentation, which, after it is generated, will be hosted by GitHub Pages. At some point, maybe we could even have that repository updated automatically when the underlying source code changes.

If you have any alternate suggestions or think this isn't a good idea, just let me know. Thanks!

[cosmoharrigan]

Here's the browsable demo from @ceefour:
http://ceefour.github.io/opencog/

[githart]

@cosmoharrigan okay, sounds good, thanks for the heads-up!

There's gotta be some git or GitHub hook that will do the update, perhaps with a GitHub subscription account (keeping things simple with no third party tools). Docker Hub (Docker's renamed automated build service) could do this, even if it seems overkill.

[cosmoharrigan]

@githart Yeah, it could probably be done using https://github.com/opencog/rest-api-documentation/settings/hooks

The browsable API is now published at http://opencog.github.io/rest-api-documentation/

[ceefour]

@cosmoharrigan I've replaced the documentation part in http://wiki.opencog.org/w/REST_API because these have entirely been copied to http://opencog.github.io/rest-api-documentation/

You can review or revert if you don't like it.