Skip to content

jmcarp/flask-apispec

Folders and files

NameName
Last commit message
Last commit date

Latest commit

db85956 · Aug 11, 2022
Aug 9, 2022
Aug 9, 2022
Aug 11, 2022
Oct 25, 2020
Mar 24, 2017
Jul 1, 2018
Oct 25, 2020
Aug 11, 2022
Mar 25, 2017
Nov 11, 2015
Mar 10, 2020
Nov 29, 2016
Aug 10, 2022
Feb 14, 2019
Oct 20, 2015
Feb 11, 2019
Oct 25, 2020
Aug 10, 2022
Oct 25, 2020

Repository files navigation

flask-apispec

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 Schema
from webargs import fields

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 apispec.ext.marshmallow import MarshmallowPlugin
from flask_apispec.extension import FlaskApiSpec

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

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

Documentation

https://flask-apispec.readthedocs.io/

Notes

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