New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make REST API documentation easier to use using Swagger #928

Merged
merged 1 commit into from Jul 14, 2014

Conversation

Projects
None yet
3 participants
@ceefour
Contributor

ceefour commented Jul 13, 2014

Make REST API easier to use using Swagger.

Can be accessed at:

image

selection_419

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.

@ceefour ceefour changed the title from Make [REST API](http://wiki.opencog.org/w/REST_API) easier to use using Swagger to Make REST API documentation easier to use using Swagger Jul 13, 2014

Make [REST API](http://wiki.opencog.org/w/REST_API) easier to use usi…
…ng [Swagger](http://petstore.swagger.wordnik.com).

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

![image](https://cloud.githubusercontent.com/assets/24123/3565412/c2746740-0ab8-11e4-84a7-b806b994bd1c.png)

![selection_419](https://cloud.githubusercontent.com/assets/24123/3565211/4bd83c78-0aaf-11e4-8ded-2153053882fe.png)

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

This comment has been minimized.

Show comment
Hide comment
@cosmoharrigan

cosmoharrigan Jul 14, 2014

Member

@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

Member

cosmoharrigan commented Jul 14, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@ceefour

ceefour Jul 14, 2014

Contributor

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.

Contributor

ceefour commented Jul 14, 2014

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

This comment has been minimized.

Show comment
Hide comment
@cosmoharrigan

cosmoharrigan Jul 14, 2014

Member

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

Member

cosmoharrigan commented Jul 14, 2014

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

This comment has been minimized.

Show comment
Hide comment
@ceefour

ceefour Jul 14, 2014

Contributor

Here it is:

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

OK
Contributor

ceefour commented Jul 14, 2014

Here it is:

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

OK
@cosmoharrigan

This comment has been minimized.

Show comment
Hide comment
@cosmoharrigan

cosmoharrigan Jul 14, 2014

Member

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

Member

cosmoharrigan commented Jul 14, 2014

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

cosmoharrigan pushed a commit that referenced this pull request Jul 14, 2014

Cosmo Harrigan
Merge pull request #928 from ceefour/swagger
Make REST API documentation easier to use using Swagger

@cosmoharrigan cosmoharrigan merged commit dda2a93 into opencog:master Jul 14, 2014

@ceefour

This comment has been minimized.

Show comment
Hide comment
@ceefour

ceefour Jul 14, 2014

Contributor

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 :)

Contributor

ceefour commented Jul 14, 2014

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

This comment has been minimized.

Show comment
Hide comment
@cosmoharrigan

cosmoharrigan Jul 14, 2014

Member

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

Member

cosmoharrigan commented Jul 14, 2014

@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 added a commit to ceefour/opencog that referenced this pull request Jul 14, 2014

@ceefour

This comment has been minimized.

Show comment
Hide comment
@ceefour

ceefour Jul 14, 2014

Contributor

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

Contributor

ceefour commented Jul 14, 2014

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

ceefour added a commit to ceefour/opencog that referenced this pull request Jul 14, 2014

ceefour added a commit to ceefour/opencog that referenced this pull request Jul 14, 2014

@cosmoharrigan

This comment has been minimized.

Show comment
Hide comment
@cosmoharrigan

cosmoharrigan Jul 16, 2014

Member

@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?

Member

cosmoharrigan commented Jul 16, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@cosmoharrigan

cosmoharrigan Jul 16, 2014

Member

@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!

Member

cosmoharrigan commented Jul 16, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@cosmoharrigan

cosmoharrigan Jul 16, 2014

Member

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

Member

cosmoharrigan commented Jul 16, 2014

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

@githart

This comment has been minimized.

Show comment
Hide comment
@githart

githart Jul 16, 2014

Member

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

Member

githart commented Jul 16, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@cosmoharrigan
Member

cosmoharrigan commented Jul 18, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@ceefour

ceefour Jul 19, 2014

Contributor

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

Contributor

ceefour commented Jul 19, 2014

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment