Flask

Install

pip install flask-smorest marshmallow

Setup

# app.py
from flask import Flask
from flask_smorest import Api
import marshmallow as ma

app = Flask(__name__)

app.config['API_TITLE'] = 'My API'
app.config['API_VERSION'] = 'v1'
app.config['OPENAPI_VERSION'] = '3.0.3'
app.config['OPENAPI_JSON_PATH'] = 'openapi.json'
app.config['OPENAPI_URL_PREFIX'] = '/'

api = Api(app)

The spec is exposed at:

http://localhost:5000/openapi.json

Define a blueprint with schemas

# routes/items.py
from flask.views import MethodView
from flask_smorest import Blueprint
import marshmallow as ma

blp = Blueprint('items', 'items', url_prefix='/items')

class ItemSchema(ma.Schema):
    id = ma.fields.Int()
    name = ma.fields.Str()

@blp.route('/<int:item_id>')
class ItemView(MethodView):
    @blp.response(200, ItemSchema)
    @blp.doc(operationId='getItem', summary='Get a single item')
    def get(self, item_id):
        return {'id': item_id, 'name': 'Widget'}

Register the blueprint:

# app.py (continued)
from routes.items import blp as items_blp
api.register_blueprint(items_blp)

Make it publicly accessible

Deploy your app or use a tunnel for local testing:

ngrok http 5000
# then use: https://<random>.ngrok.io/openapi.json

Verify

Visit /openapi.json in your browser. You should see a valid OpenAPI 3.x JSON document.

Paste this URL into Automiel’s import step.