Flasgger

Easy Swagger UI for your Flask API

<a target="_blank" href="https://www.paypal.com/cgi-bin/webscr?cmd=_donations&amp;business=rochacbruno%40gmail%2ecom&amp;lc=BR&amp;item_name=Flasgger&amp;no_note=0&amp;currency_code=USD&amp;bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHostedGuest"><img alt='Donate with Paypal' src='http://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif' /></a>

Flasgger is a Flask extension to extract OpenAPI-Specification from all Flask views registered in your API.

Flasgger also comes with SwaggerUI embedded so you can access http://localhost:5000/apidocs and visualize and interact with your API resources.

Flasgger also provides validation of the incoming data, using the same specification it can validates if the data received as a POST, PUT, PATCH is valid against the schema defined using YAML, Python dictionaries or Marshmallow Schemas.

Flasgger can work with simple function views or MethodViews using docstring as specification, or using @swag_from decorator to get specification from YAML or dict and also provides SwaggerView which can use Marshmallow Schemas as specification.

Flasgger is compatible with Flask-RESTful so you can use Resources and swag specifications together, take a look at restful example.

Flasgger also supports Marshmallow APISpec as base template for specification, if you are using APISPec from Marshmallow take a look at apispec example.

Table of Contents

• Top Contributors
• Examples and demo app
  • Docker
• Installation
• Getting started
  • Using docstrings as specification
  • Using external YAML files
  • Using dictionaries as raw specs
  • Using Marshmallow Schemas
  • Using <strong>Flask RESTful</strong> Resources
  • Auto-parsing external YAML docs and MethodViews
  • Handling multiple http methods and routes for a single function
• Use the same data to validate your API POST body.
  • Custom validation
  • Validation Error handling
• Get defined schemas as python dictionaries
• HTML sanitizer
• Swagger UI and templates
• OpenAPI 3.0 Support
  • Externally loading Swagger UI and jQuery JS/CSS
• Initializing Flasgger with default data.
  • Getting default data at runtime
  • Behind a reverse proxy
• Customize default configurations
  • Extracting Definitions
  • Python2 Compatibility

Created by gh-md-toc

Top Contributors

Examples and demo app

There are some example applications and you can also play with examples in Flasgger demo app

NOTE: all the examples apps are also test cases and run automatically in Travis CI to ensure quality and coverage.

Docker

The examples and demo app can also be built and run as a Docker image/container:

docker build -t flasgger .
docker run -it --rm -p 5000:5000 --name flasgger flasgger

Then access the Flasgger demo app at http://localhost:5000 .

Installation

under your virtualenv do:

Ensure you have latest setuptools

pip install -U setuptools

then install beta version (recommended)

pip install flasgger==0.9.7b2

or (latest stable for legacy apps)

pip install flasgger==0.9.5

or (dev version)

pip install https://github.com/flasgger/flasgger/tarball/master

NOTE: If you want to use Marshmallow Schemas you also need to run pip install marshmallow apispec

How to run tests

(You may see the command in .travis.yml for before_install part)

In your virtualenv:

pip install -r requirements.txt
pip install -r requirements-dev.txt
make test

Getting started

Using docstrings as specification

Create a file called for example colors.py

from flask import Flask, jsonify
from flasgger import Swagger

app = Flask(__name__)
swagger = Swagger(app)

@app.route('/colors/<palette>/')
def colors(palette):
    """Example endpoint returning a list of colors by palette
    This is using docstrings for specifications.
    ---
    parameters:
      - name: palette
        in: path
        type: string
        enum: ['all', 'rgb', 'cmyk']
        required: true
        default: all
    definitions:
      Palette:
        type: object
        properties:
          palette_name:
            type: array
            items:
              $ref: '#/definitions/Color'
      Color:
        type: string
    responses:
      200:
        description: A list of colors (may be filtered by palette)
        schema:
          $ref: '#/definitions/Palette'
        examples:
          rgb: ['red', 'green', 'blue']
    """
    all_colors = {
        'cmyk': ['cyan', 'magenta', 'yellow', 'black'],
        'rgb': ['red', 'green', 'blue']
    }
    if palette == 'all':
        result = all_colors
    else:
        result = {palette: all_colors.get(palette)}

    return jsonify(result)

app.run(debug=True)

Now run:

python colors.py

And go to: http://localhost:5000/apidocs/

You should get:

Using external YAML files

Save a new file colors.yml

Example endpoint returning a list of colors by palette
In this example the specification is taken from external YAML file
---
parameters:
  - name: palette
    in: path
    type: string
    enum: ['all', 'rgb', 'cmyk']
    required: true
    default: all
definitions:
  Palette:
    type: object
    properties:
      palette_name:
        type: array
        items:
          $ref: '#/definitions/Color'
  Color:
    type: string
responses:
  200:
    description: A list of colors (may be filtered by palette)
    schema:
      $ref: '#/definitions/Palette'
    examples:
      rgb: ['red', 'green', 'blue']

lets use the same example changing only the view function.

from flasgger import swag_from

@app.route('/colors/<palette>/')
@swag_from('colors.yml')
def colors(palette):
    ...

If you do not want to use the decorator you can use the docstring file: shortcut.

@app.route('/colors/<palette>/')
def colors(palette):
    """
    file: colors.yml
    """
    ...

Using dictionaries as raw specs

Create a Python dictionary as:

specs_dict = {
  "parameters": [
    {
      "name": "palette",
      "in": "path",
      "type": "string",
      "enum": [
        "all",
        "rgb",
        "cmyk"
      ],
      "required": "true",
      "default": "all"
    }
  ],
  "definitions": {
    "Palette": {
      "type": "object",
      "properties": {
        "palette_name": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Color"
          }
        }
      }
    },
    "Color": {
      "type": "string"
    }
  },
  "responses": {
    "200": {
      "description": "A list of colors (may be filtered by palette)",
      "schema": {
        "$ref": "#/definitions/Palette"
      },
      "examples": {
        "rgb": [
          "red",
          "green",
          "blue"
        ]
      }
    }
  }
}

Now take the same function and use the dict in the place of YAML file.

@app.route('/colors/<palette>/')
@swag_from(specs_dict)
def colors(