Package: pyramid-apispec
pyramid_apispecpyramid_apispec allows you to create anOpenAPI specification fileusingapispecand an online OpenAPI explorer using theSwagger UIproject for yourPyramidapplication and itsmarshmallowschemas.Installationpip install pyramid_apispecBasic usageCheck out the demo folder and minimal application example by running:pip install -e '.[demo]'
python demo/app.pyYou can then visit your API explorer page athttp://0.0.0.0:6543/api-explorer.Or visitgenerated documentation herefor an example of the demo site.
(please note that actual REST API is not working in GitHub pages)Note:The demo site is using OpenAPI/Swagger v2.0.
OpenAPI 3.0 is supported as well, it just uses a different YAML schema so pay attention to examples online.ExampleThis example is based onapispec,
adapted for Pyramid andpyramid_apispec(updated as ofapispecv5.1.0).This example is using OpenAPI 3.0.2Hinting a route and its view:Add the OpenAPI YAML to the view docstring.
Optionally use Marshmallow schemas to define the inputs and outputs.importuuidfrommarshmallowimportSchema,fieldsfrompyramid.viewimportview_config# Optional marshmallow supportclassCategorySchema(Schema):id=fields.Int()name=fields.Str(required=True)classPetSchema(Schema):categories=fields.List(fields.Nested(CategorySchema))name=fields.Str()@view_config(route_name="random_pet",renderer="json")defrandom_pet(request):"""A cute furry animal endpoint.---get:description: Get a random petsecurity:- ApiKeyAuth: []responses:200:description: Return a petcontent:application/json:schema: PetSchema"""# Hardcoded example datapet_data={"name":"sample_pet_"+str(uuid.uuid1()),"categories":[{"id":1,"name":"sample_category"}],}returnPetSchema().dump(pet_data)For more details on how to document the API, see theOpenAPI specification.Rendering the spec as JSON response:fromapispecimportAPISpecfromapispec.ext.marshmallowimportMarshmallowPluginfrompyramid.viewimportview_configfrompyramid_apispec.helpersimportadd_pyramid_paths@view_config(route_name="openapi_spec",renderer="json")defapi_spec(request):"""View to generate the OpenAPI JSON output."""spec=APISpec(title="Some API",version="1.0.0",openapi_version="3.0.2",plugins=[MarshmallowPlugin()],)# Optional security scheme supportapi_key_scheme={"type":"apiKey","in":"header","name":"X-API-Key"}spec.components.security_scheme("ApiKeyAuth",api_key_scheme)# Optionally register Marshmallow schema for more flexibilityspec.components.schema("Pet",schema=PetSchema)# inspect the `random_pet` route and generate operations from docstringadd_pyramid_paths(spec,'random_pet',request=request)returnspec.to_dict()Adding the API Explorer ViewTo complement the specification file generation, this package can also provide an API explorer
for your application's API via the Swagger UI project:config.include("pyramid_apispec.views")config.add_route("openapi_spec","/openapi.json")config.pyramid_apispec_add_explorer(spec_route_name="openapi_spec")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 Pyramidpermissionor
custom callable (script_generatorargument) to override the default JavaScript
configuration of Swagger UI.The default URL for the explorer is/api-explorer. This setting is controlled
via theexplorer_route_pathargument - the route is registered aspyramid_apispec.api_explorer_path.Running testspip install -e '.[dev]'
tox