Add Swagger support

[reubano]

https://developers.helloreverb.com/swagger/

Flask peewee and mongodb currently support it. Swagger auto generates docs for your rest api.

[klinkin]

In my own project to describe API i use http://apiary.io

[reubano]

Looks interesting. Is there a way to auto generate the api blueprint? I.e, if i add a new model, flask-restless creates the resource but i dont want to have to manually add the new resource to the blueprint.

[jfinkels]

This would be a decent amount of work, so I'm probably going to put off doing it myself for a while. Also, would this be its own separate Flask extension? It seems that hapyak/flask-peewee-swagger is its own Flask extension.

[reubano]

Yeah, I guess you have a point about it being a separate extension. "Flask-SQLAlchemy-Swagger" maybe? Do you have any recommendations for other API auto-documentation services that would work with Flask-Restless?

[jfinkels]

I'm not sure, sorry. Also, it may not be technically possible to separate the documentation generation code from the API creation code, so it may be necessary to include such code in Flask-Restless, I just don't know.

[reubano]

I've been playing around with apiary and while there isn't a way to auto generate api blueprints, they do integrate with github so pushing a new blueprint will auto update the documentation. It shouldn't be too hard to build a script that parses the flask model to create a skeleton blueprint. @jfinkels what part of your source code do you recommend I reference to help me with this task?

[jfinkels]

Well, I'm not sure exactly what you need, but in the helpers module we have functions like get_columns(model) and get_relations(model), which return a dictionary or list of columns or relations. There is also the is_like_list(instance, relation) function, which may be of use.

[dnordberg]

I'm was looking to implement this, I gave up eventually. I do however have a script which stubs out the JSON files required by Swagger for all urls under the api endpoint.

https://gist.github.com/dnordberg/5658957
https://gist.github.com/dnordberg/5658936
https://gist.github.com/dnordberg/5658920

[dnordberg]

Was looking to dynamically generate the docs by taking a blueprint generated using the flask_restless.manager.create_api_blueprint function and passing it to a SwaggerDocumentationManager and figuring out which urls correspond to the resource. The SwaggerDocumentationManager.register function would look something like this

def register(self, blueprint, model=None, models=None, **opts):
    # pass blueprint so we can get urls mapped to the blueprint name
    # pass model if its a flask-restless resource mapped to a model
    # pass models which are used together with this resource
    # opts would include options that override the resource and operation specifications
    ...

Decorators would be used to define specifications for non flask-restless API endpoints.

Whats difficult is we don't have access to any of the options provided to flask-restless in generating the endpoints. E.g. include and exclude columns and relations.

[reubano]

Looks good but can you combine the gists into 1 so it is easier to read? Github lets you have multiple files in one gist. Thanks!

Sent from my iPhone

On May 27, 2013, at 11:40 PM, Daniel Nordberg notifications@github.com wrote:

I'm also looking to implement this, I don't have a working solution yet but have a script which helps generate the JSON files required by Swagger.

https://gist.github.com/dnordberg/5658957
https://gist.github.com/dnordberg/5658936
https://gist.github.com/dnordberg/5658920

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

[dnordberg]

Couldn't see how to do this, here it is: https://gist.github.com/dnordberg/5661696

[reubano]

Thanks! Much better. So what about it isn't working correctly? And what is
the license? I've been tinkering on something for apiary and your code will
help me to fill in some of the gaps.

[dnordberg]

MIT license.

It works fine, just it doesn't dynamically generate the JSON required for Swagger, so any model changes or API changes need you to rerun the commands. It doesn't remove previously edited resource specifications only adds new ones, so if you edit your resource specifications it shouldn't override them, however, if existing resources have changed, they may need to be updated.

I use Git diff and patch to check out the changes and make modifications. Other than that, it doesn't handle somethings well, e.g. doesn't take into account exclude and include column rules, sub resources have incorrect descriptions, error codes are stubs and need to be updated.

Other than that, it should work fine to stub out the Swagger JSON files.

[dnordberg]

One important distinction between apiary and Swagger is that documentation generated using apiary can't be self hosted.

[reubano]

Doesn't matter to me. I haven't figured out how swagger works and apiary
seems much more straightforward. I just link my repo and modify the
blueprint whenever my models change.

[jfinkels]

There is at least some support for this at https://github.com/mmessmore/flask-restless-swagger (thanks to @mwhite for the reference). I'm going to close this issue as I prefer it to be supported outside of Flask-Restless itself.