Falcon plugin for apispec documentation generator.
Project description
falcon-apispec
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
- Fork falcon-apispec on Github
- 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 hashes)
Built Distribution
Close
Hashes for falcon_apispec-0.4.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 611ff323c56f6a853c1bb4f1ed3601aa5d5ec5762595a4772c458c7bfb78082e |
|
MD5 | d57e22f51680759b422b41bc65e6d904 |
|
BLAKE2-256 | 493d95689bc42c6405c4ce66f01c0380aee5f5edf23a866e987e79b09e5d0338 |