Getting started

flaskdoc provides decorators that can be used to automatically generate openapi v3 specifications from existing flask routes. This sections describes how to get started quickly.

Step 1. Install

flaskdoc is available on PyPi,

Step 2. Configure

Register flaskdoc with your flask app instance. This requires top level openapi models like Info, Server, Tags etc. These should match your api’s expectations. Flaskdoc exposes swagger specific models via flaskdoc.swagger

Note

default url is /docs, this can be customized by setting the docs_path parameter of register_openapi. You can also use Redoc instead of the default swagger ui, by setting the use_redoc parameter to True.

from flaskdoc import swagger

contact_info = swagger.Contact(
    name="Contact Name",
    email="Contact Email",
    url="Contact URL",
)
license_info = swagger.License(
    name="License Name",
    url="License URL",
)

info = swagger.Info(
    title="API title",
    version="API version",
    contact=contact_info,
    license=license_info,
)

Registering openapi routes using openapi involves simply doing

Note

See Snippets section for more detailed examples on how to use the register_openapi function

import flask
from flaskdoc import register_openapi, swagger

app = flask.Flask("Fancy flask App)
info = swagger.Info(...)

register_openapi(app, info=info)

Under the hood, flaskdoc simply does:

ui.add_url_rule("/", view_func=register_docs_ui, methods=["GET"])
ui.add_url_rule("/<path:path>", view_func=register_docs_ui, methods=["GET"])
ui.add_url_rule("/openapi.json", view_func=register_json_path, methods=["GET"])
ui.add_url_rule("/openapi.yaml", view_func=register_yaml_path, methods=["GET"])
app.register_blueprint(ui, url_prefix=docs_path)

Step 3. Start Documenting

Again flaskdoc exposes http method decorators that can be used in documenting your api via flaskdoc.swagger.

Simple GET

blp = flask.Blueprint("Dummy", __name__, url_prefix="/v1")

@swagger.GET(
    tags=["getEcho"],
    operation_id="getEcho",
    parameters=[swagger.PathParameter(name="sample", schema=str)],
    description="Retrieve echos wit Get",
    responses={
        "200": swagger.ResponseObject(
            description="Success", content=jo.PlainText(schema=jo.Email()),
        )
    },
)
@blp.route("/echo/<string:sample>", methods=["GET"])
def echo(sample: str):
    """
    Sample GET request
    Returns: Echos back whatever was sent

    """
    return sample

Simple POST

blp = flask.Blueprint("Dummy", __name__, url_prefix="/v1")
@swagger.POST(
    tags=["administrator"],
    description="Posts an Echo",
    responses={"201": swagger.ResponseObject(description="OK")},
)
@blp.route("/echo", methods=["POST"])
def post():
    req = flask.request.get_json(force=True)
    return flask.jsonify(req), 200

Data Models

Flaskdoc includes a framework agnostic way of automatically converting native python classes into swagger compatible json schema. See Data Models for more information.

import flask
from flaskdoc import swagger

ts = flask.Blueprint(__name__)

class OakTown:
""" Sample class without any special annotations """

    oaks = None
    smugs = 1  # type: int
    snux = "2"  # type: str


@swagger.GET(
  tags=["listOaks"],
  summary="Lists all towns with oaks",
  responses={
    "200": swagger.JsonType(schema=[OakTown])
  }
)
@ts.route("/list", methods=["GET"])
def list_oaks():
    return []


@swagger.POST(
  tags=["createTown],
  summary="Create a new OakTown",
  request_body=swagger.RequestBody(
    content=[swagger.JsonType(schema=OakTown), swagger.XmlType(schema=OakTown)]
  )
)
@ts.route("", methods=["POST"]
def create_town():
    return OakTown())