Skip to main content

Extract swagger specs from your flask project

Project description

A Swagger 2.0 spec extractor for Flask


pip install flask-swagger

Flask-swagger provides a method (swagger) that inspects the Flask app for endpoints that contain YAML docstrings with Swagger 2.0 Operation objects.

class UserAPI(MethodView):

    def post(self):
        Create a new user
          - users
          - schema:
              id: Group
                 type: string
                 description: the group's name
          - in: body
            name: body
              id: User
                - email
                - name
                  type: string
                  description: email for user
                  type: string
                  description: name for user
                  description: address for user
                    id: Address
                        type: string
                        type: string
                        type: string
                        type: string
                  type: array
                  description: list of groups
                    $ref: "#/definitions/Group"
            description: User created
        return {}

Flask-swagger supports docstrings in methods of MethodView classes and regular Flask view functions.

Following YAML conventions, flask-swagger searches for ---, everything preceding is provided as summary (first line) and description (following lines) for the endpoint while everything after is parsed as a swagger Operation object.

In order to support inline definition of Schema objects in Parameter and Response objects, flask-swagger veers a little off from the standard. We require an id field for the inline Schema which is then used to correctly place the Schema object in the Definitions object.

Schema objects can be defined in a definitions section within the docstrings (see group object above) or within responses or parameters (see user object above). We alo support schema objects nested within the properties of other Schema objects. An example is shown above with the address property of User.

To expose your Swagger specification to the world you provide a Flask route that does something along these lines

from flask import Flask, jsonify
from flask_swagger import swagger

app = Flask(__name__)

def spec():
    return jsonify(swagger(app))

Note that the Swagger specification returned by swagger(app) is as minimal as it can be. It’s your job to override and add to the specification as you see fit.

def spec():
    swag = swagger(app)
    swag['info']['version'] = "1.0"
    swag['info']['title'] = "My API"
    return jsonify(swag)


Swagger-UI is the reason we embarked on this mission to begin with, flask-swagger does not however include Swagger-UI. Simply follow the awesome documentation over at and point your swaggerUi.url to your new flask-swagger endpoint and enjoy.


Flask-swagger builds on ideas and code from flask-sillywalk and flask-restful-swagger

Project details

Download files

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

Files for flask-swagger, version 0.2.14
Filename, size File type Python version Upload date Hashes
Filename, size flask_swagger-0.2.14-py2-none-any.whl (7.3 kB) File type Wheel Python version py2 Upload date Hashes View
Filename, size flask-swagger-0.2.14.tar.gz (8.6 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page