Skip to main content

Build and document REST APIs with Flask and apispec

Project description

===========
flask-apispec
===========

.. image:: https://img.shields.io/pypi/v/flask-apispec.svg
:target: http://badge.fury.io/py/flask-apispec
:alt: Latest version

.. image:: https://img.shields.io/travis/jmcarp/flask-apispec/master.svg
:target: https://travis-ci.org/jmcarp/flask-apispec
:alt: Travis-CI

.. image:: https://img.shields.io/codecov/c/github/jmcarp/flask-apispec/master.svg
:target: https://codecov.io/github/jmcarp/flask-apispec
:alt: 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
-------

.. code-block::

pip install flask-apispec

Quickstart
----------

.. code-block:: python

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:

.. code-block:: python

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:

.. code-block:: python

from apispec import APISpec
from flask_apispec.apidoc import Documentation

spec = APISpec(
title='pets',
version='v1',
plugins=['apispec.ext.marshmallow'],
)
docs = Documentation(app, spec)

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

docs.spec.to_dict() # Complete Swagger JSON

Notes
-----

**flask-apispec** isn't stable yet, and the interface and internals may change. Bug reports and pull requests are much appreciated.

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

.. _webargs: https://webargs.readthedocs.org/
.. _marshmallow: https://marshmallow.readthedocs.org/
.. _apispec: https://apispec.readthedocs.org/
.. _Flask-RESTful: https://flask-restful.readthedocs.org/
.. _Flask-RESTplus: https://flask-restplus.readthedocs.org/

Project details


Download files

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

Source Distribution

flask-apispec-0.1.3.tar.gz (8.1 kB view hashes)

Uploaded Source

Built Distribution

flask_apispec-0.1.3-py2.py3-none-any.whl (11.6 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page