Skip to main content
Help the Python Software Foundation raise $60,000 USD by December 31st!  Building the PSF Q4 Fundraiser

Pyramid plugin for openapi spec generation

Project description


pyramid_apispec allows you to create an OpenAPI specification file using apispec and an online OpenAPI explorer using the Swagger UI project for your Pyramid application and its marshmallow schemas.


pip install pyramid_apispec

Basic usage

Check out the demo folder and minimal application example by running:

pip install -e '.[demo]'
python demo/

You can then visit your API explorer page at


Visit generated documentation here (please note that actual REST API is not working in github pages)

Hinting a route and its view:

@view_config(route_name='foo_route', renderer='json')
def foo_view():
    """A greeting endpoint.

    x-extension: value
        description: some description
                description: response for 200 code
                    $ref: #/definitions/BarBodySchema
    return 'hi'

Rendering the spec as JSON response:

from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from pyramid_apispec.helpers import add_pyramid_paths

@view_config(route_name='openapi_spec', renderer='json')
def api_spec(request):
    spec = APISpec(
        title='Some API',
    # using marshmallow plugin here
    spec.definition('SomeFooBody', schema=MarshmallowSomeFooBodySchema)

    # inspect the `foo_route` and generate operations from docstring
    add_pyramid_paths(spec, 'foo_route', request=request)

    # inspection supports filtering via pyramid add_view predicate arguments
        spec, 'bar_route', request=request, request_method='post')
    return spec.to_dict()

Adding the API explorer view

To complement the specification file generation, this package can also provide an API explorer for your application's API via the Swagger UI project:

config.add_route("openapi_spec", "/openapi.json")

By default you need to pass the route name of the view that serves the OpenAPI specification in your application. If needed you can specify a Pyramid permission or custom callable (script_generator argument) to override the default JavaScript configuration of Swagger UI.

The default URL for the explorer is /api-explorer. This setting is controlled via the explorer_route_path argument - the route is registered as pyramid_apispec.api_explorer_path.

Running tests

pip install -e '.[dev]'

Project details

Download files

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

Files for pyramid-apispec, version 0.4
Filename, size File type Python version Upload date Hashes
Filename, size pyramid_apispec-0.4-py2.py3-none-any.whl (10.3 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size pyramid_apispec-0.4.tar.gz (10.4 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page