https://github.com/grktsh/falcon-oas

Design first approach with OpenAPI 3 for Falcon
https://github.com/grktsh/falcon-oas

falcon oas openapi python

Last synced: 3 months ago
JSON representation

Design first approach with OpenAPI 3 for Falcon

• Host: GitHub
• URL: https://github.com/grktsh/falcon-oas
• Owner: grktsh
• License: apache-2.0
• Created: 2018-11-04T16:44:47.000Z (about 6 years ago)
• Default Branch: master
• Last Pushed: 2021-04-20T17:40:01.000Z (almost 4 years ago)
• Last Synced: 2024-04-29T03:20:57.981Z (9 months ago)
• Topics: falcon, oas, openapi, python
• Language: Python
• Homepage:
• Size: 216 KB
• Stars: 7
• Watchers: 3
• Forks: 2
• Open Issues: 3
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE.txt

Awesome Lists containing this project

README

        
falcon-oas

==========

.. image:: https://img.shields.io/pypi/v/falcon-oas.svg

   :alt: PyPI

   :target: https://pypi.org/project/falcon-oas

.. image:: https://github.com/grktsh/falcon-oas/workflows/CI/badge.svg

   :alt: CI

   :target: https://github.com/grktsh/falcon-oas/actions

.. image:: https://codecov.io/gh/grktsh/falcon-oas/branch/master/graph/badge.svg

   :alt: Coverage

   :target: https://codecov.io/gh/grktsh/falcon-oas

Prerequisites

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

- Validated OpenAPI 3 document

  - falcon-oas does not validate OpenAPI 3 document itself at runtime.  It should be validated in advance.

Features

--------

- Request validation and unmarshaling

- Access control

- Association of Path Item Objects and resource classes in Falcon

Example

-------

.. code:: python

    class PetItem:

        def on_get(self, req, resp, pet_id):

            pet = get_pet_by_id(pet_id)

            resp.media = pet.to_dict()

        def on_delete(self, req, resp, pet_id):

            pet = delete_pet_by_id(pet_id)

            resp.status = falcon.HTTP_NO_CONTENT

    with open('/path/to/openapi.json') as f:

        spec_dict = json.load(f)

    api = falcon_oas.OAS(spec_dict).create_api()

Here is the part of its OpenAPI 3 document in YAML:

.. code:: yaml

    paths:

      /api/v1/pets/{pet_id}:

        x-falcon-oas-implementation: path.to.PetItem

        get:

          responses:

            '200':

              description: A pet.

        delete:

          responses:

            '204':

              description: Successful deletion.

          security:

          - api_key: []

        parameters:

        - name: pet_id

          in: path

          required: true

          schema:

            type: integer

    components:

      securitySchemes:

        api_key:

          x-falcon-oas-implementation: path.to.api_key_validator

          type: apiKey

          name: X-API-Key

          in: header

``pet_id`` path parameter is unmarshaled to ``int`` without `Field Converters `_ since it is defined as ``integer`` type.

``DELETE /api/v1/pets/{pet_id}`` requests are protected by the ``api_key`` security scheme. The corresponding responder is processed only if it grants the request. Otherwise, 403 Forbidden error occurs automatically.

``x-falcon-oas-implementation`` associates Path Item Object and the REST resource class in Falcon so that falcon-oas automatically calls ``falcon.API.add_route`` with its path and the resource instance. Alternatively, the resource instance can be set programmatically using ``oas.resolve_path_item('/api/v1/pets/{pet_id}', PetItem())``, which allows to inject dependencies into the resource instance.

Also ``x-falcon-oas-implementation`` associates Security Scheme Object and the access control function so that falcon-oas automatically handles Security Requirement Object in each request. See ``falcon_oas.extensions`` for details. Alternatively, the access control function can be set programmatically using ``oas.resolve_security_scheme('api_key', validate_api_key)``, which allows to inject dependencies into the access control function.

``req.context['oas']``

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

``req.context['oas'].user``

    Authorized user.

``req.context['oas'].parameters``

    Unmarshaled request parameters in dict.

``req.context['oas'].request_body``

    Unmarshaled request body.

Problems

--------

Media Type: ``application/problem+json`` only

Unmarshal Error

~~~~~~~~~~~~~~~

HTTP status code: 400

- ``"type"``: ``"https://pypi.org/project/falcon-oas/0.3.0/#unmarshal-error"``

- ``"title"``: ``"Unmarshal Error"``

- ``"status"``: ``400``

- ``"parameters"``: (optional) The array of parameter error objects

- ``"request_body"``: (optional) The array of request body error objects

The parameter error object and the request body error object have the following members from ``jsonschema.ValidationError``:

- ``"path"``: The path to the offending element within the instance

- ``"validator"``: The name of the failed validator

- ``"message"``: A human readable message explaining the error

Example:

.. code:: json

    {

      "type": "https://pypi.org/project/falcon-oas/0.3.0/#unmarshal-error",

      "title": "Unmarshal Error",

      "status": 400,

      "parameters": [

        {

          "path": ["path", "pet_id"],

          "validator": "type",

          "message": "'me' is not of type 'integer'"

        }

      ],

      "request_body": [

        {

          "path": ["name"],

          "validator": "type",

          "message": "42 is not of type 'string'"

        }

      ]

    }