flasgger

library0.9.7.1pypypi✓ verified 24d ago

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.

web-framework serialization

pip install flasgger

github ↗package ↗

INSTALL

IMPORT

SIG · FLASGGER

flasgger

web-frameworkpythonv0.9.7.1

Install

5.4s avg

Import

804ms

Disk

44MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.9.7.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.812s · 44.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 5.4s · import 0.796s · 46MB

44MB installed

● package 44MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Swagger

✓ from flasgger import Swagger

swag_from

✓ from flasgger import swag_from

Decorator used to reference a separate YAML file for Swagger specs.

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)

flasgger --version

Debug

Known issues

breakingFlasgger 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.

affects: <0.9.5

breakingIncompatibility 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.

affects: 0.9.5 - 0.9.6b1

gotchaWhen 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.

affects: 0.9.6b1 and newer when using OpenAPI 3

gotchaFlasgger 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.

affects: 0.9.4 and newer

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'flasgger'

The 'flasgger' package is not installed in your Python environment or the active virtual environment.

fix

Run `pip install flasgger` or `pip3 install flasgger` in your terminal to install the library. If using a virtual environment, ensure it is activated before installation.

AttributeError: 'NoneType' object has no attribute 'get'

This often occurs when the OpenAPI/Swagger specification in a docstring or external YAML file is malformed, leading Flasgger's parser to return `None` when expecting a dictionary-like object with a 'get' method. It means Flasgger cannot properly extract the API definition for one of your endpoints.

fix

Carefully review your API endpoint docstrings or external YAML/YML specification files for syntax errors, incorrect indentation, or missing required fields. Ensure the YAML adheres to the OpenAPI/Swagger specification. Using a YAML linter or validator can help identify issues. Setting `app.config['SWAGGER']['debug'] = True` might also provide more detailed error messages.

Flasgger failed to load API definition / INTERNAL SERVER ERROR /apispec_1.json

This general error indicates that the Swagger UI is unable to fetch or parse the generated API specification JSON. It's frequently a symptom of underlying issues in your API definitions (docstrings or YAML files) that prevent Flasgger from successfully generating the `/apispec_1.json` endpoint's content.

fix

Check your Flask application logs for more specific errors (e.g., `AttributeError` related to malformed YAML). Ensure all docstrings are valid YAML/OpenAPI specifications. If using external YAML files, verify their paths and content. Temporarily simplifying your API definitions to isolate the problematic endpoint can help in debugging.

AttributeError: 'dict' object has no attribute 'startswith'

This error typically arises when using the `@swag_from` decorator, where `flasgger` expects a string path to an external YAML file but receives a dictionary object instead, or vice-versa, indicating a mismatch in how the spec is provided.

fix

Ensure that the argument passed to `@swag_from` is a string representing the file path (e.g., `'path/to/my_spec.yml'`) and not an already loaded dictionary. If you intend to use a dictionary, ensure it's structured correctly for direct use by Flasgger, or convert your Path object to a string before passing it.

Upgrade

Version history

0.9.7.1latest on PyPI · released May 18, 2023

Audit

Dependencies

FlaskrequiredCore web framework integration.

PyYAMLrequiredUsed for parsing YAML specifications.

jsonschemarequiredUsed for JSON schema validation.

apispecrequiredLibrary for generating OpenAPI specifications.

swagger_ui_bundlerequiredProvides the static files for Swagger UI.

Agent activity

18 hits · last 30 days

node

Resources

githubhttps://github.com/flasgger/flasgger ↗

packagehttps://pypi.org/project/flasgger/ ↗