Metadata-Version: 2.1
Name: Flask-First
Version: 0.9.1
Summary: Flask extension for using "specification first" principle via OpenAPI specification.
Home-page: https://github.com/flask-pro/flask-first
Author: Konstantin Fadeev
Author-email: fadeev@stantis.ru
License: MIT
Project-URL: Bug Tracker, https://github.com/flask-pro/flask-first/issues
Platform: UNKNOWN
Classifier: Framework :: Flask
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Flask (>=2.0.2)
Requires-Dist: openapi-spec-validator (>=0.3.1)
Requires-Dist: marshmallow (>=3.14.1)

# Flask-First

Flask extension for using "specification first" principle.

Features:

* `Application Factory` supported.
* Serializing `request.args` and storing result in `request.first_args`.
* Validating path parameters from url.
* Validating arguments from url.
* Validating JSON from request.
* Validating JSON from response.
* Provides a Swagger UI.

----

Limitations

* Full specification in one file.

## Installing

Install and update using `pip`:

```shell
$ pip install flask_first
```

Simple example
--------------
OpenAPI 3 specification file `openapi.yaml`:

```yaml
openapi: 3.0.3
info:
  title: Simple API for Flask-First
  version: 1.0.0
paths:
  /{name}:
    parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: index
      summary: Returns a list of items
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
```

File with application initialization `main.py`:

```python
import os

from flask import Flask
from flask_first import First

basedir = os.path.abspath(os.path.dirname(__file__))
path_to_spec = os.path.join(basedir, 'openapi.yaml')

app = Flask(__name__)
app.config['FIRST_RESPONSE_VALIDATION'] = True
first = First(path_to_spec, app=app, swagger_ui_path='/docs')

def index(name):
    return {'message': name}

first.add_view_func(index)

if __name__ == '__main__':
    app.run()

```

Run application:

```shell
$ python main.py
```

Check url in browser `http://127.0.0.1:5000/username`. Check SwaggerUI url in browser `http://127.0.0.1:5000/docs`.

## Settings

`FIRST_RESPONSE_VALIDATION` - Default: `False`. Enabling response body validation. Useful when
developing. May be disabled in a production environment.

## Additional documentation

* [OpenAPI Documentation](https://swagger.io/specification/).
* [OpenAPI on GitHub](https://github.com/OAI/OpenAPI-Specification).
* [JSON Schema Documentation](https://json-schema.org/specification.html).


