https://github.com/plangrid/flask-rebar

Flask-Rebar combines flask, marshmallow, and swagger for robust REST services.
https://github.com/plangrid/flask-rebar

acsbp public

Last synced: 2 months ago
JSON representation

Flask-Rebar combines flask, marshmallow, and swagger for robust REST services.

• Host: GitHub
• URL: https://github.com/plangrid/flask-rebar
• Owner: plangrid
• License: mit
• Created: 2018-02-26T17:39:13.000Z (almost 7 years ago)
• Default Branch: master
• Last Pushed: 2024-09-16T21:02:02.000Z (4 months ago)
• Last Synced: 2024-09-17T02:30:40.258Z (4 months ago)
• Topics: acsbp, public
• Language: Python
• Homepage:
• Size: 9.16 MB
• Stars: 231
• Watchers: 119
• Forks: 38
• Open Issues: 51
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGELOG.rst
  • Contributing: CONTRIBUTING.rst
  • License: LICENSE
  • Codeowners: CODEOWNERS
  • Security: SECURITY.md
  • Authors: AUTHORS

Awesome Lists containing this project

• awesome-flask - Flask-Rebar - Combines Flask, [marshmallow](https://marshmallow.readthedocs.io/), and [OpenAPI](https://www.openapis.org/) for robust REST services. (Third-Party Extensions / APIs)
• jimsghstars - plangrid/flask-rebar - Flask-Rebar combines flask, marshmallow, and swagger for robust REST services. (Python)
• best-of-web-python - GitHub - 47% open · ⏱️ 15.04.2024): (Flask Utilities)

README

        
Flask-Rebar

===========

.. image:: https://readthedocs.org/projects/flask-rebar/badge/?version=latest

   :target: http://flask-rebar.readthedocs.io/en/latest/?badge=latest

   :alt: Documentation Status

.. image:: https://github.com/plangrid/flask-rebar/actions/workflows/tag.yml/badge.svg

   :target: https://github.com/plangrid/flask-rebar/actions/workflows/tag.yml

   :alt: CI Status

.. image:: https://badge.fury.io/py/flask-rebar.svg

   :target: https://badge.fury.io/py/flask-rebar

   :alt: PyPI status

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg

   :target: https://github.com/ambv/black

   :alt: Code style

.. image:: https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg

   :target: https://www.contributor-covenant.org/

   :alt: Code of Conduct

|

Flask-Rebar combines `flask `_, `marshmallow `_, and `swagger `_ for robust REST services.

Features

--------

* **Request and Response Validation** - Flask-Rebar relies on schemas from the popular Marshmallow package to validate incoming requests and marshal outgoing responses.

* **Automatic Swagger Generation** - The same schemas used for validation and marshaling are used to automatically generate OpenAPI specifications (a.k.a. Swagger). This also means automatic documentation via `Swagger UI `_.

* **Error Handling** - Uncaught exceptions from Flask-Rebar are converted to appropriate HTTP errors.

Example

-------

.. code-block:: python

   from flask import Flask

   from flask_rebar import errors, Rebar

   from marshmallow import fields, Schema

   from my_app import database

   rebar = Rebar()

   # All handler URL rules will be prefixed by '/v1'

   registry = rebar.create_handler_registry(prefix='/v1')

   class TodoSchema(Schema):

       id = fields.Integer()

       complete = fields.Boolean()

       description = fields.String()

   # This schema will validate the incoming request's query string

   class GetTodosQueryStringSchema(Schema):

       complete = fields.Boolean()

   # This schema will marshal the outgoing response

   class GetTodosResponseSchema(Schema):

       data = fields.Nested(TodoSchema, many=True)

   @registry.handles(

       rule='/todos',

       method='GET',

       query_string_schema=GetTodosQueryStringSchema(),

       response_body_schema=GetTodosResponseSchema(), # for versions <= 1.7.0, use marshal_schema

   )

   def get_todos():

       """

       This docstring will be rendered as the operation's description in

       the auto-generated OpenAPI specification.

       """

       # The query string has already been validated by `query_string_schema`

       complete = rebar.validated_args.get('complete')

       ...

       # Errors are converted to appropriate HTTP errors

       raise errors.Forbidden()

       ...

       # The response will be marshaled by `marshal_schema`

       return {'data': []}

   def create_app(name):

       app = Flask(name)

       rebar.init_app(app)

       return app

   if __name__ == '__main__':

       create_app(__name__).run()

For a more complete example, check out the example app at `examples/todo.py `_. Some example requests to this example app can be found at `examples/todo_output.md `_.

Installation

------------

.. code-block::

   pip install flask-rebar

Replacing static swagger-ui files

---------------------------------

If you'd like to replace swagger-ui's static files (`flask_rebar/swagger_ui/static`) with those of the latest release,

run the following from the root of the project.

.. code-block::

    

    curl -L https://api.github.com/repos/swagger-api/swagger-ui/tarball | tar -xv --directory=flask_rebar/swagger_ui/static --strip-components=2 "*/dist/"

Documentation

-------------

More extensive documentation can be found  `here `_.

Extensions

----------

Flask-Rebar is extensible! Here are some open source extensions:

* `Flask-Rebar-Auth0 `_ - `Auth0 `_ authenticator for Flask-Rebar

Contributing

------------

There is still work to be done, and contributions are encouraged! Check out the `contribution guide `_ for more information.