Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!

Build and document REST APIs with Flask and apispec

Project description

Latest version Documentation status Travis-CI Code coverage

flask-apispec is a lightweight tool for building REST APIs in Flask. flask-apispec uses webargs for request parsing, marshmallow for response formatting, and apispec to automatically generate Swagger markup. You can use flask-apispec with vanilla Flask or a fuller-featured framework like Flask-RESTful.

Install

pip install flask-apispec

Quickstart

from flask import Flask
from flask_apispec import use_kwargs, marshal_with

from marshmallow import fields, Schema

from .models import Pet

app = Flask(__name__)

class PetSchema(Schema):
    class Meta:
        fields = ('name', 'category', 'size')

@app.route('/pets')
@use_kwargs({'category': fields.Str(), 'size': fields.Str()})
@marshal_with(PetSchema(many=True))
def get_pets(**kwargs):
    return Pet.query.filter_by(**kwargs)

flask-apispec works with function- and class-based views:

from flask import make_response
from flask_apispec.views import MethodResource

class PetResource(MethodResource):

    @marshal_with(PetSchema)
    def get(self, pet_id):
        return Pet.query.filter(Pet.id == pet_id).one()

    @use_kwargs(PetSchema)
    @marshal_with(PetSchema, code=201)
    def post(self, **kwargs):
        return Pet(**kwargs)

    @use_kwargs(PetSchema)
    @marshal_with(PetSchema)
    def put(self, pet_id, **kwargs):
        pet = Pet.query.filter(Pet.id == pet_id).one()
        pet.__dict__.update(**kwargs)
        return pet

    @marshal_with(None, code=204)
    def delete(self, pet_id):
        pet = Pet.query.filter(Pet.id == pet_id).one()
        pet.delete()
        return make_response('', 204)

flask-apispec generates Swagger markup for your view functions and classes. By default, Swagger JSON is served at /swagger/, and Swagger-UI at /swagger-ui/.

from apispec import APISpec
from flask_apispec.extension import FlaskApiSpec

app.config.update({
    'APISPEC_SPEC': APISpec(
        title='pets',
        version='v1',
        plugins=['apispec.ext.marshmallow'],
    ),
    'APISPEC_SWAGGER_URL': '/swagger/',
})
docs = FlaskApiSpec(app)

docs.register(get_pets)
docs.register(PetResource)

Notes

flask-apispec is strongly inspired by Flask-RESTful and Flask-RESTplus, but attempts to provide similar functionality with greater flexibility and less code.

Project details


Release history Release notifications

This version
History Node

0.6.0.post0

History Node

0.5.0

History Node

0.4.2

History Node

0.4.1.post0

History Node

0.4.1

History Node

0.4.0

History Node

0.3.2

History Node

0.3.1

History Node

0.3.0

History Node

0.2.0

History Node

0.1.3

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
flask_apispec-0.6.0.post0-py2.py3-none-any.whl (1.0 MB) Copy SHA256 hash SHA256 Wheel py2.py3 Mar 11, 2018
flask-apispec-0.6.0.post0.tar.gz (1.0 MB) Copy SHA256 hash SHA256 Source None Mar 11, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page