Skip to main content

Falcon plugin for apispec documentation generator.

Project description

falcon-apispec

Build Status codecov PyPI License: MIT

apispec plugin that generates OpenAPI specification (aka Swagger) for Falcon web applications.

Installation

pip install falcon-apispec

Works with apispec v1.0+.

Example Application

from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
import falcon
from falcon_apispec import FalconPlugin
from marshmallow import Schema, fields


# Optional marshmallow support
class CategorySchema(Schema):
    id = fields.Int()
    name = fields.Str(required=True)

class PetSchema(Schema):
    category = fields.Nested(CategorySchema, many=True)
    name = fields.Str()


# Create Falcon web app
app = falcon.API()

class RandomPetResource:
    def on_get(self, req, resp):
        """A cute furry animal endpoint.
        ---
        description: Get a random pet
        responses:
            200:
                description: A pet to be returned
                schema: PetSchema
        """
        pet = get_random_pet()  # returns JSON
        resp.media = pet

# create instance of resource
random_pet_resource = RandomPetResource()
# pass into `add_route` for Falcon
app.add_route("/random", random_pet_resource)


# Create an APISpec
spec = APISpec(
    title='Swagger Petstore',
    version='1.0.0',
    openapi_version='2.0',
    plugins=[
        FalconPlugin(app),
        MarshmallowPlugin(),
    ],
)

# Register entities and paths
spec.components.schema('Category', schema=CategorySchema)
spec.components.schema('Pet', schema=PetSchema)
# pass created resource into `path` for APISpec
spec.path(resource=random_pet_resource)

Generated OpenAPI Spec

spec.to_dict()
# {
#   "info": {
#     "title": "Swagger Petstore",
#     "version": "1.0.0"
#   },
#   "swagger": "2.0",
#   "paths": {
#     "/random": {
#       "get": {
#         "description": "A cute furry animal endpoint.",
#         "responses": {
#           "200": {
#             "schema": {
#               "$ref": "#/definitions/Pet"
#             },
#             "description": "A pet to be returned"
#           }
#         },
#       }
#     }
#   },
#   "definitions": {
#     "Pet": {
#       "properties": {
#         "category": {
#           "type": "array",
#           "items": {
#             "$ref": "#/definitions/Category"
#           }
#         },
#         "name": {
#           "type": "string"
#         }
#       }
#     },
#     "Category": {
#       "required": [
#         "name"
#       ],
#       "properties": {
#         "name": {
#           "type": "string"
#         },
#         "id": {
#           "type": "integer",
#           "format": "int32"
#         }
#       }
#     }
#   },
# }

spec.to_yaml()
# definitions:
#   Pet:
#     enum: [name, photoUrls]
#     properties:
#       id: {format: int64, type: integer}
#       name: {example: doggie, type: string}
# info: {description: 'This is a sample Petstore server.  You can find out more ', title: Swagger Petstore, version: 1.0.0}
# parameters: {}
# paths: {}
# security:
# - apiKey: []
# swagger: '2.0'
# tags: []

Contributing

Setting Up for Local Development

  1. Fork falcon-apispec on Github
  2. Install development requirements. Virtual environments are highly recommended
pip install -r requirements.txt

Running Tests

pytest

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

falcon-apispec-0.4.0.tar.gz (5.4 kB view details)

Uploaded Source

Built Distribution

falcon_apispec-0.4.0-py3-none-any.whl (5.0 kB view details)

Uploaded Python 3

File details

Details for the file falcon-apispec-0.4.0.tar.gz.

File metadata

  • Download URL: falcon-apispec-0.4.0.tar.gz
  • Upload date:
  • Size: 5.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/41.2.0 requests-toolbelt/0.9.1 tqdm/4.46.0 CPython/3.8.1

File hashes

Hashes for falcon-apispec-0.4.0.tar.gz
Algorithm Hash digest
SHA256 3be2d7a544852fb6ec78bcdd27f28cb62418337ab85ab23685632f7946f667e5
MD5 650f8905ef3bf236a65d7cee28467826
BLAKE2b-256 9c6a4b55d1d01cf23f66c3acf514a70568ac0abc55e33b9b83238e9a2da8f5f7

See more details on using hashes here.

File details

Details for the file falcon_apispec-0.4.0-py3-none-any.whl.

File metadata

  • Download URL: falcon_apispec-0.4.0-py3-none-any.whl
  • Upload date:
  • Size: 5.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/41.2.0 requests-toolbelt/0.9.1 tqdm/4.46.0 CPython/3.8.1

File hashes

Hashes for falcon_apispec-0.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 611ff323c56f6a853c1bb4f1ed3601aa5d5ec5762595a4772c458c7bfb78082e
MD5 d57e22f51680759b422b41bc65e6d904
BLAKE2b-256 493d95689bc42c6405c4ce66f01c0380aee5f5edf23a866e987e79b09e5d0338

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page