falcon-apispec
apispec plugin that generates OpenAPI specification (aka Swagger) for Falcon web applications.
Apispec 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 specification
Installation
pip install falcon-apispecOptionaly:
pip install marshmallowWorks 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
- Fork falcon-apispec on Github
- Install development requirements. Virtual environments are highly recommended
pip install -r requirements.txtRunning Tests
pytest