{"id":14986719,"url":"https://github.com/grktsh/falcon-oas","last_synced_at":"2025-08-26T00:17:26.199Z","repository":{"id":52704290,"uuid":"156103388","full_name":"grktsh/falcon-oas","owner":"grktsh","description":"Design first approach with OpenAPI 3 for Falcon","archived":false,"fork":false,"pushed_at":"2021-04-20T17:40:01.000Z","size":221,"stargazers_count":7,"open_issues_count":3,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-29T03:20:57.981Z","etag":null,"topics":["falcon","oas","openapi","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grktsh.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-04T16:44:47.000Z","updated_at":"2021-06-09T16:06:56.000Z","dependencies_parsed_at":"2022-09-19T05:10:13.265Z","dependency_job_id":null,"html_url":"https://github.com/grktsh/falcon-oas","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grktsh%2Ffalcon-oas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grktsh%2Ffalcon-oas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grktsh%2Ffalcon-oas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grktsh%2Ffalcon-oas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grktsh","download_url":"https://codeload.github.com/grktsh/falcon-oas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248482923,"owners_count":21111401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["falcon","oas","openapi","python"],"created_at":"2024-09-24T14:13:24.803Z","updated_at":"2025-04-11T21:31:11.878Z","avatar_url":"https://github.com/grktsh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"falcon-oas\n==========\n\n.. image:: https://img.shields.io/pypi/v/falcon-oas.svg\n   :alt: PyPI\n   :target: https://pypi.org/project/falcon-oas\n\n.. image:: https://github.com/grktsh/falcon-oas/workflows/CI/badge.svg\n   :alt: CI\n   :target: https://github.com/grktsh/falcon-oas/actions\n\n.. image:: https://codecov.io/gh/grktsh/falcon-oas/branch/master/graph/badge.svg\n   :alt: Coverage\n   :target: https://codecov.io/gh/grktsh/falcon-oas\n\nPrerequisites\n-------------\n\n- Validated OpenAPI 3 document\n\n  - falcon-oas does not validate OpenAPI 3 document itself at runtime.  It should be validated in advance.\n\nFeatures\n--------\n\n- Request validation and unmarshaling\n- Access control\n- Association of Path Item Objects and resource classes in Falcon\n\nExample\n-------\n\n.. code:: python\n\n    class PetItem:\n        def on_get(self, req, resp, pet_id):\n            pet = get_pet_by_id(pet_id)\n            resp.media = pet.to_dict()\n\n        def on_delete(self, req, resp, pet_id):\n            pet = delete_pet_by_id(pet_id)\n            resp.status = falcon.HTTP_NO_CONTENT\n\n\n    with open('/path/to/openapi.json') as f:\n        spec_dict = json.load(f)\n    api = falcon_oas.OAS(spec_dict).create_api()\n\nHere is the part of its OpenAPI 3 document in YAML:\n\n.. code:: yaml\n\n    paths:\n      /api/v1/pets/{pet_id}:\n        x-falcon-oas-implementation: path.to.PetItem\n        get:\n          responses:\n            '200':\n              description: A pet.\n        delete:\n          responses:\n            '204':\n              description: Successful deletion.\n          security:\n          - api_key: []\n        parameters:\n        - name: pet_id\n          in: path\n          required: true\n          schema:\n            type: integer\n    components:\n      securitySchemes:\n        api_key:\n          x-falcon-oas-implementation: path.to.api_key_validator\n          type: apiKey\n          name: X-API-Key\n          in: header\n\n``pet_id`` path parameter is unmarshaled to ``int`` without `Field Converters \u003chttps://falcon.readthedocs.io/en/stable/api/routing.html#field-converters\u003e`_ since it is defined as ``integer`` type.\n\n``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.\n\n``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.\n\nAlso ``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.\n\n``req.context['oas']``\n----------------------\n\n``req.context['oas'].user``\n    Authorized user.\n\n``req.context['oas'].parameters``\n    Unmarshaled request parameters in dict.\n\n``req.context['oas'].request_body``\n    Unmarshaled request body.\n\nProblems\n--------\n\nMedia Type: ``application/problem+json`` only\n\nUnmarshal Error\n~~~~~~~~~~~~~~~\n\nHTTP status code: 400\n\n- ``\"type\"``: ``\"https://pypi.org/project/falcon-oas/0.3.0/#unmarshal-error\"``\n- ``\"title\"``: ``\"Unmarshal Error\"``\n- ``\"status\"``: ``400``\n- ``\"parameters\"``: (optional) The array of parameter error objects\n- ``\"request_body\"``: (optional) The array of request body error objects\n\nThe parameter error object and the request body error object have the following members from ``jsonschema.ValidationError``:\n\n- ``\"path\"``: The path to the offending element within the instance\n- ``\"validator\"``: The name of the failed validator\n- ``\"message\"``: A human readable message explaining the error\n\nExample:\n\n.. code:: json\n\n    {\n      \"type\": \"https://pypi.org/project/falcon-oas/0.3.0/#unmarshal-error\",\n      \"title\": \"Unmarshal Error\",\n      \"status\": 400,\n      \"parameters\": [\n        {\n          \"path\": [\"path\", \"pet_id\"],\n          \"validator\": \"type\",\n          \"message\": \"'me' is not of type 'integer'\"\n        }\n      ],\n      \"request_body\": [\n        {\n          \"path\": [\"name\"],\n          \"validator\": \"type\",\n          \"message\": \"42 is not of type 'string'\"\n        }\n      ]\n    }\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrktsh%2Ffalcon-oas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrktsh%2Ffalcon-oas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrktsh%2Ffalcon-oas/lists"}