{"id":48923458,"url":"https://github.com/osanj/falcon-swoop","last_synced_at":"2026-04-17T05:35:01.399Z","repository":{"id":344249278,"uuid":"867855386","full_name":"osanj/falcon-swoop","owner":"osanj","description":"Build simple APIs on top of falcon with pydantic data models (FastAPI style), automated OpenAPI spec generation included","archived":false,"fork":false,"pushed_at":"2026-03-13T19:39:31.000Z","size":73,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-14T07:47:03.312Z","etag":null,"topics":["api","asgi","falcon","falcon-framework","openai","pydantic","python","swagger-ui","wsgi"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/osanj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-04T21:27:00.000Z","updated_at":"2026-03-13T19:37:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/osanj/falcon-swoop","commit_stats":null,"previous_names":["osanj/falcon-swoop"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/osanj/falcon-swoop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osanj%2Ffalcon-swoop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osanj%2Ffalcon-swoop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osanj%2Ffalcon-swoop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osanj%2Ffalcon-swoop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osanj","download_url":"https://codeload.github.com/osanj/falcon-swoop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osanj%2Ffalcon-swoop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31917099,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["api","asgi","falcon","falcon-framework","openai","pydantic","python","swagger-ui","wsgi"],"created_at":"2026-04-17T05:34:59.972Z","updated_at":"2026-04-17T05:35:01.378Z","avatar_url":"https://github.com/osanj.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# falcon-swoop\n\nEasy-to-define typed API resources for [falcon](https://github.com/falconry/falcon) based on [pydantic](https://github.com/pydantic/pydantic) models bringing some FastAPI style\nconvenience to your favorite web framework. Automatic OpenAPI doc generation included.\nIt is fully opt-in: Use it for all your resources, start attaching typed operations\nto an existing app or just add a single typed resource to your project.\nOpenAPI documentation can also be added manually for old or very complex operations that don't fit in this framework.\n\n```commandline\npip install falcon-swoop\n```\n\n(compatible with Falcon 4.x and Pydantic 2.x)\n\n\n## User Guide\n\n### Quickstart\n\nTo use falcon-swoop follow these steps:\n1. subclass from `SwoopResource`\n2. create a method for your API operation and type-hint it with Pydantic classes for input and output\n3. decorate that method with `@operation`\n4. wrap the falcon `App` with `SwoopApp` and register the swoop resources there\n\n\n```python\nimport falcon.asgi\nfrom falcon_swoop import SwoopApp, SwoopResource, operation\nfrom pydantic import BaseModel, Field\n\n\ndef store_message_in_db(author: str, text: str) -\u003e str:\n  # implement storage in database here!\n  return \"new_id\"\n\n\nclass CreateMessageInput(BaseModel):\n  author: str\n  text: str = Field(min_length=20)\n\n  \nclass CreateMessageOutput(BaseModel):\n  message_uid: str\n\n  \nclass NewMessageController(SwoopResource):\n  def __init__(self):\n    super().__init__(route=\"/api/message\")\n      \n  @operation(method=\"POST\")\n  async def create_message(self, message: CreateMessageInput) -\u003e CreateMessageOutput:\n    message_uid = store_message_in_db(message.author, message.text)\n    return CreateMessageOutput(message_uid=message_uid)\n\n  \ndef build_app() -\u003e falcon.asgi.App:\n  app = falcon.asgi.App()\n  swoop = SwoopApp(\n    app,\n    title=\"Example App\",\n    version=\"0.1.0\",\n    spec_json_route=\"/api/openapi.json\",\n    spec_swagger_route=\"/api/swagger.html\",\n  )\n  swoop.add_route(NewMessageController())\n  return app\n```\n\nOnce the application is running, new JSON data can be submitted on `POST /message` according to `CreateMessageInput`,\nsimilarly the application will respond with JSON according to `CreateMessageOutput`. The OpenAPI specification can then\nbe accessed as JSON on `/api/openapi.json` or human-readable at `/api/swagger.html`.\n\nThis concludes the basics, keep reading for more details!\n\n\n### Tips\n\n* falcon-swoop works for both synchronous and asynchronous falcon applications\n* for operations that are too complicated for falcon-swoop, but should still show up in the OpenAPI specification, the `@operation_doc` decorator can be used to provide manual documentation on conventional falcon responder methods, such as `on_get`, `on_post` and so on\n* use `header_param`, `query_param` and `path_param` to model inputs other than the HTTP body\n* for binary input and output use `OpBinary` (or `OpAsgiBinary` for async operations)\n* for more finegrained response control (status code, headers, ...) return `OpOutput[SomeModel]` or  `OpOutput[OpBinary]`\n* when access to the entire falcon request and response is required, add an input with `OpContext` (or `OpAsgiContext` for async operations)\n\n\n### Full Example\n\nCheck out [src/falcon_swoop_example](src/falcon_swoop_example) for a full example. To run it `gunicorn` needs to be\ninstalled, then the application can be started with the commands below. Check the logs on which routes the OpenAPI\nspecification and the Swagger UI can be accessed.\n```\ncd src\n./falcon_swoop_example.sh\n```\n\n\n## Development Guide\n\n```\npip install .  # to install main dependencies\npip install -e \".[dev]\"  # to install main and dev dependencies\n\nruff check --fix\nruff format\nmypy\npytest -v\nnox  # requires separate install\n\nhatchling build -t wheel\n```\n\n\n## Open Items\n\n- [ ] add security schemes to openapi docgen\n- [ ] warning for pydantic models that declare fields of type bytes\n- [ ] handle missing annotations for input, params, context and return value\n- [ ] add support for (de)serialization to yaml and other formats\n- [ ] utility spec class for Multipart form data\n  - [ ] makes parsing easy\n  - [ ] integrates with OpenAPI generation\n- [ ] make sure snake_case to camelCase works easily (especially for query and path params)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosanj%2Ffalcon-swoop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosanj%2Ffalcon-swoop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosanj%2Ffalcon-swoop/lists"}