Metadata-Version: 2.1
Name: flaskdocs
Version: 0.0.1
Summary: A packed to help generate documentation automatically for flask endpoints.
Home-page: https://github.com/mrincredibuell/flaskdocs
Author: Joseph L Buell V
Author-email: jlrbuellv@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Description-Content-Type: text/markdown
Requires-Dist: Flask
Requires-Dist: schema

__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.

