Skip to main content

Extract swagger specs from your flask project

Project description

A Swagger 2.0 spec extractor for Flask

Install:

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
        ---
        tags:
          - users
        definitions:
          - schema:
              id: Group
              properties:
                name:
                 type: string
                 description: the group's name
        parameters:
          - in: body
            name: body
            schema:
              id: User
              required:
                - email
                - name
              properties:
                email:
                  type: string
                  description: email for user
                name:
                  type: string
                  description: name for user
                address:
                  description: address for user
                  schema:
                    id: Address
                    properties:
                      street:
                        type: string
                      state:
                        type: string
                      country:
                        type: string
                      postalcode:
                        type: string
                groups:
                  type: array
                  description: list of groups
                  items:
                    $ref: "#/definitions/Group"
        responses:
          201:
            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__)

@app.route("/spec")
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.

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

Swagger-UI

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 https://github.com/swagger-api/swagger-ui and point your swaggerUi.url to your new flask-swagger endpoint and enjoy.

Acknowledgments

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.

Source Distribution

flask-swagger-0.2.14.tar.gz (8.6 kB view details)

Uploaded Source

Built Distribution

flask_swagger-0.2.14-py2-none-any.whl (7.3 kB view details)

Uploaded Python 2

File details

Details for the file flask-swagger-0.2.14.tar.gz.

File metadata

  • Download URL: flask-swagger-0.2.14.tar.gz
  • Upload date:
  • Size: 8.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.19.1 setuptools/40.6.3 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/2.7.15

File hashes

Hashes for flask-swagger-0.2.14.tar.gz
Algorithm Hash digest
SHA256 b4085f5bc36df4c20b6548cd1413adc9cf35719b0f0695367cd542065145294d
MD5 fac8fd796e86c41ec8dceeed326fd08d
BLAKE2b-256 b2a9a6c05fbc592ac482bf9557e47957c429d2be8cb8addfbc92853fb862ea8f

See more details on using hashes here.

File details

Details for the file flask_swagger-0.2.14-py2-none-any.whl.

File metadata

  • Download URL: flask_swagger-0.2.14-py2-none-any.whl
  • Upload date:
  • Size: 7.3 kB
  • Tags: Python 2
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.19.1 setuptools/40.6.3 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/2.7.15

File hashes

Hashes for flask_swagger-0.2.14-py2-none-any.whl
Algorithm Hash digest
SHA256 3caddb1311388eafc86f82f8e64ba386a5df6b84e5f16dfae19ca08173eba216
MD5 9afde40d9d426a43402b5b4bf18c43e4
BLAKE2b-256 18782da3bf35a978127085ae6aff85d601b8842a4204fe88a506e23d0c79acc7

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page