Swagger UI documentationΒΆ

By default flask-restplus provide a Swagger UI documentation on your API root.

from flask import Flask
from flask.ext.restplus import Api, Resource, fields

app = Flask(__name__)
api = Api(app, version='1.0', title='Sample API',
    description='A sample API',
)

@api.route('/my-resource/<id>', endpoint='my-resource')
@api.doc(params={'id': 'An ID'})
class MyResource(Resource):
    def get(self, id):
        return {}

    @api.doc(responses={403: 'Not Authorized'})
    def post(self, id):
        api.abort(403)


if __name__ == '__main__':
    app.run(debug=True)

If you run the code below and visit your API root URL (http://localhost:5000) you will have an automatically generated SwaggerUI documentation.

You can specify a custom validator url by setting config.SWAGGER_VALIDATOR_URL:

from flask import Flask
from flask.ext.restplus import Api, Resource, fields

app = Flask(__name__)
app.config.SWAGGER_VALIDATOR_URL = 'http://domain.com/validator'

api = Api(app, version='1.0', title='Sample API',
    description='A sample API',
)

'...'

if __name__ == '__main__':
    app.run(debug=True)

You can also specify the initial expansion state with the config.SWAGGER_UI_DOC_EXPANSION setting (none, list or full):

from flask import Flask
from flask.ext.restplus import Api, Resource, fields

app = Flask(__name__)
app.config.SWAGGER_UI_DOC_EXPANSION = 'list'

api = Api(app, version='1.0', title='Sample API',
    description='A sample API',
)

'...'

if __name__ == '__main__':
    app.run(debug=True)

You can totally disable the generated Swagger UI by setting doc=False:

from flask import Flask
from flask.ext.restplus import Api, Resource, fields

app = Flask(__name__)
api = Api(app, doc=False)

'...'

if __name__ == '__main__':
    app.run(debug=True)

You can also provide a custom UI by reusing the apidoc blueprint or rolling your own from scratch.

from flask import Flask, Blueprint, url_for
from flask.ext.restplus import API, apidoc

app = Flask(__name__)
blueprint = Blueprint('api', __name__, url_prefix='/api')
api = Api(blueprint, doc='/doc/')

'...'

@api.documentation
def swagger_ui():
    return apidoc.ui_for(api)


app.register_blueprint(blueprint)