Getting started¶

Let’s install small example Flask app:

my_app
├── app.py
└── my_api.py

cd my_app
python -m venv .venv
source .venv/bin/activate
pip install flask-marshmallow-openapi

my_api.py:

import flask
import marshmallow as ma
from flask_marshmallow_openapi import open_api


api = flask.Blueprint("my_api", __name__)


class BookSchema(ma.Schema):
    id = ma.fields.Integer(as_string=True)
    title = ma.fields.String(allow_none=False)
    publisher = ma.fields.String(allow_none=False)
    isbn = ma.fields.String(allow_none=False)


@open_api.get_list(response_schema=BookSchema)
@api.route("/books", methods=["GET"])
def books_list():
    return flask.jsonify(
        BookSchema(many=True).dump(
            [
                {"id": 24, "title": "title", "publisher": "publisher", "isbn": "isbn"},
                {"id": 42, "title": "title", "publisher": "publisher", "isbn": "isbn"},
            ]
        )
    )

app.py:

from flask_marshmallow_openapi import OpenAPISettings, OpenAPI

import flask

from my_api import api

app = flask.Flask(__name__)
app.register_blueprint(api, url_prefix="/v1")


conf = OpenAPISettings(
    api_version="v1", api_name="My API", app_package_name="my_api", mounted_at="/v1"
)
docs = OpenAPI(config=conf)
docs.init_app(app)

Check routes:

$ flask routes

Endpoint               Methods  Rule
---------------------  -------  -------------------------------
my_api.books_list      GET      /v1/books
open_api.re_doc        GET      /v1/docs/re_doc
open_api.static        GET      /v1/docs/static/<path:filename>
open_api.swagger_json  GET      /v1/docs/static/swagger.json
open_api.swagger_ui    GET      /v1/docs/swagger_ui
open_api.swagger_yaml  GET      /v1/docs/static/swagger.yaml
static                 GET      /static/<path:filename>

Run the app:

flask run

And see the docs in local ReDoc:

ReDoc

Full example application¶

Many examples in this documentation had been collected into complete Flask application that demonstrates everything documented here.

Download: