Flasgger

0.9.7.1 · active · verified Sat Apr 11

Flasgger is a Python library that integrates Swagger UI into Flask applications, automatically extracting Swagger/OpenAPI specifications from docstrings within your Flask project's endpoints. The current version is 0.9.7.1, with development continuing through beta releases and stable updates to address compatibility and new features.

Warnings

breaking Flasgger versions 0.9.5 and newer officially dropped support for Python 2. Projects still on Python 2 must use Flasgger 0.9.4 or older.
Fix: Upgrade to Python 3.x or pin Flasgger version to 0.9.4 or earlier for Python 2 projects.
breaking Incompatibility with Flask 2.3+ was resolved in Flasgger 0.9.7b1 (and subsequent releases like 0.9.7.1). Older Flasgger versions may experience issues with Flask's JSON encoder changes.
Fix: Upgrade Flasgger to at least 0.9.7b1 (or the latest stable) if using Flask 2.3 or newer.
gotcha When migrating to OpenAPI 3.0.0, Flasgger (from 0.9.6b1) will move top-level `#/definitions` to `#/components/schemas`. Existing Swagger 2.0 specifications might require updates to match the OpenAPI 3 structure.
Fix: Review and update your Swagger specifications to use `#/components/schemas` for reusable data models when `config['SWAGGER']['openapi'] = '3.0.0'` is set.
gotcha Flasgger 0.9.4 updated its supported versions for `apispec` (to 2.0.2) and `jsonschema` (to >=3.0.1). Ensure these dependencies are compatible with other libraries in your project to avoid conflicts.
Fix: If encountering dependency resolution issues, check the `apispec` and `jsonschema` versions installed and consider using virtual environments or dependency pinning.

Install

pip install flasgger Install Flasgger

Imports

Swagger
```
from flasgger import Swagger
```
swag_from
```
from flasgger import swag_from
```
Decorator used to reference a separate YAML file for Swagger specs.

Quickstart

This quickstart demonstrates how to initialize Flasgger with a Flask app and document a simple endpoint using a docstring. Once run, navigate to `/apidocs` in your browser to see the generated Swagger UI.

from flask import Flask, jsonify
from flasgger import Swagger

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

@app.route("/hello")
def hello_world():
    """
    Hello World! endpoint.
    ---    
    responses:
      200:
        description: A simple hello world message
    """
    return jsonify(hello="world")

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

view raw JSON →