{"id":18662115,"url":"https://github.com/alysivji/falcon-apispec","last_synced_at":"2025-05-10T22:58:44.640Z","repository":{"id":44672535,"uuid":"142485436","full_name":"alysivji/falcon-apispec","owner":"alysivji","description":"apispec plugin that generates OpenAPI specification (aka Swagger Docs) for Falcon web applications.","archived":false,"fork":false,"pushed_at":"2022-12-08T02:51:31.000Z","size":31,"stargazers_count":44,"open_issues_count":12,"forks_count":31,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-10T22:58:39.285Z","etag":null,"topics":["api","apispec","documentation","falcon","openapi","python","rest","spec","specification","swagger"],"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/alysivji.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}},"created_at":"2018-07-26T19:32:11.000Z","updated_at":"2024-09-11T21:53:42.000Z","dependencies_parsed_at":"2023-01-24T06:30:17.760Z","dependency_job_id":null,"html_url":"https://github.com/alysivji/falcon-apispec","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alysivji%2Ffalcon-apispec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alysivji%2Ffalcon-apispec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alysivji%2Ffalcon-apispec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alysivji%2Ffalcon-apispec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alysivji","download_url":"https://codeload.github.com/alysivji/falcon-apispec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253492648,"owners_count":21916965,"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":["api","apispec","documentation","falcon","openapi","python","rest","spec","specification","swagger"],"created_at":"2024-11-07T08:09:59.384Z","updated_at":"2025-05-10T22:58:44.624Z","avatar_url":"https://github.com/alysivji.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# falcon-apispec\n\n[![Build Status](https://travis-ci.org/alysivji/falcon-apispec.svg?branch=master)](https://travis-ci.org/alysivji/falcon-apispec) [![codecov](https://codecov.io/gh/alysivji/falcon-apispec/branch/master/graph/badge.svg)](https://codecov.io/gh/alysivji/falcon-apispec) [![PyPI](https://img.shields.io/pypi/v/falcon-apispec.svg)](https://pypi.org/project/falcon-apispec/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n[apispec](https://github.com/marshmallow-code/apispec) plugin that generates OpenAPI specification (aka Swagger) for [Falcon](https://falconframework.org/) web applications.\n\nApispec uses three sources of information. Basic information is directly given to `APISpec()`. The plugin reads information about paths from the Falcon app. Information about an object could be given by [marshmallow](https://marshmallow.readthedocs.io/en/stable/) specification\n\n## Installation\n\n```console\npip install falcon-apispec\n```\n\nOptionaly:\n```console\npip install marshmallow\n```\n\n\nWorks with `apispec v1.0+`.\n\n## Example Application\n\n```python\nfrom apispec import APISpec\nfrom apispec.ext.marshmallow import MarshmallowPlugin\nimport falcon\nfrom falcon_apispec import FalconPlugin\nfrom marshmallow import Schema, fields\n\n\n# Optional marshmallow support\nclass CategorySchema(Schema):\n    id = fields.Int()\n    name = fields.Str(required=True)\n\nclass PetSchema(Schema):\n    category = fields.Nested(CategorySchema, many=True)\n    name = fields.Str()\n\n\n# Create Falcon web app\napp = falcon.API()\n\nclass RandomPetResource:\n    def on_get(self, req, resp):\n        \"\"\"A cute furry animal endpoint.\n        ---\n        description: Get a random pet\n        responses:\n            200:\n                description: A pet to be returned\n                schema: PetSchema\n        \"\"\"\n        pet = get_random_pet()  # returns JSON\n        resp.media = pet\n\n# create instance of resource\nrandom_pet_resource = RandomPetResource()\n# pass into `add_route` for Falcon\napp.add_route(\"/random\", random_pet_resource)\n\n\n# Create an APISpec\nspec = APISpec(\n    title='Swagger Petstore',\n    version='1.0.0',\n    openapi_version='2.0',\n    plugins=[\n        FalconPlugin(app),\n        MarshmallowPlugin(),\n    ],\n)\n\n# Register entities and paths\nspec.components.schema('Category', schema=CategorySchema)\nspec.components.schema('Pet', schema=PetSchema)\n# pass created resource into `path` for APISpec\nspec.path(resource=random_pet_resource)\n```\n\n### Generated OpenAPI Spec\n\n```python\nspec.to_dict()\n# {\n#   \"info\": {\n#     \"title\": \"Swagger Petstore\",\n#     \"version\": \"1.0.0\"\n#   },\n#   \"swagger\": \"2.0\",\n#   \"paths\": {\n#     \"/random\": {\n#       \"get\": {\n#         \"description\": \"A cute furry animal endpoint.\",\n#         \"responses\": {\n#           \"200\": {\n#             \"schema\": {\n#               \"$ref\": \"#/definitions/Pet\"\n#             },\n#             \"description\": \"A pet to be returned\"\n#           }\n#         },\n#       }\n#     }\n#   },\n#   \"definitions\": {\n#     \"Pet\": {\n#       \"properties\": {\n#         \"category\": {\n#           \"type\": \"array\",\n#           \"items\": {\n#             \"$ref\": \"#/definitions/Category\"\n#           }\n#         },\n#         \"name\": {\n#           \"type\": \"string\"\n#         }\n#       }\n#     },\n#     \"Category\": {\n#       \"required\": [\n#         \"name\"\n#       ],\n#       \"properties\": {\n#         \"name\": {\n#           \"type\": \"string\"\n#         },\n#         \"id\": {\n#           \"type\": \"integer\",\n#           \"format\": \"int32\"\n#         }\n#       }\n#     }\n#   },\n# }\n\nspec.to_yaml()\n# definitions:\n#   Pet:\n#     enum: [name, photoUrls]\n#     properties:\n#       id: {format: int64, type: integer}\n#       name: {example: doggie, type: string}\n# info: {description: 'This is a sample Petstore server.  You can find out more ', title: Swagger Petstore, version: 1.0.0}\n# parameters: {}\n# paths: {}\n# security:\n# - apiKey: []\n# swagger: '2.0'\n# tags: []\n```\n\n## Contributing\n\n### Setting Up for Local Development\n\n1. Fork falcon-apispec on Github\n2. Install development requirements. Virtual environments are highly recommended\n\n```console\npip install -r requirements.txt\n```\n\n### Running Tests\n\n```console\npytest\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falysivji%2Ffalcon-apispec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falysivji%2Ffalcon-apispec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falysivji%2Ffalcon-apispec/lists"}