Skip to main content

A packed to help generate documentation automatically for flask endpoints.

Project description

flaskdocs is a lightweight wrapper around a flask app which aims to centralize both validation and documentation of an API. Declare the schemas you're accept/return, and flaskdocs will let you generate an openapi.json file, as well as validating incoming requests and returning errors to the client if a request doesn't match the given schema.

Example usage:

Declare a flask app and pass it to a flaskdocs API as follows:

from flask import Flask, jsonify

from flaskdocs import API
from flaskdocs.schema import (
    JsonSchema,
    QueryParameterSchema,
    Literal,
    Use,
)

app = Flask(__name__)

api = API(
    title="example",
    version="0.0.1",
    description="Here's an example API",
    app=app,
)

@api.route(
    name="Add Numbers",
    path="/add",
    methods=["GET"],
    description="Add two numbers together and return the sum",
    query_parameter_schema=QueryParameterSchema({
        # use "Use" here to tell the parser try calling float, rather
        # than doing a type check, because queryParameters always come
        # in as strings
        Literal("x", description="The first number to add"): Use(float),
        Literal("y", description="The second number to add"): Use(float),
    }),
    response_schema={200: JsonSchema({
        Literal("sum", description="The sum x + y"): float
    })},
)
def add(x: float, y: float):
    return jsonify({"sum": x + y})

api.output_openapi("example/openapi-spec.json")

To run a more complete example (found in the example folder) run FLASK_APP=example/server.py python -m flask run from this directory.

Project details


Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for flaskdocs, version 0.0.1
Filename, size File type Python version Upload date Hashes
Filename, size flaskdocs-0.0.1-py3-none-any.whl (6.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size flaskdocs-0.0.1.tar.gz (5.3 kB) File type Source Python version None Upload date Hashes View

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page