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 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 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 also be defined 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 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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.