starlette_jsonapi.openapi module

Experimental support for generating OpenAPI 3.x specifications.

Example:

from apispec import APISpec
from starlette.applications import Starlette
from starlette_jsonapi.openapi import JSONAPISchemaGenerator, JSONAPIMarshmallowPlugin

schemas = JSONAPISchemaGenerator(
    APISpec(
        title='Example API',
        version='1.0',
        openapi_version='3.0.3',
        info={'description': 'An example API.'},
        plugins=[JSONAPIMarshmallowPlugin()],
    )
)

app = Starlette()

# register resources routes on app

schema_dict = schemas.get_schema(app.routes)

class starlette_jsonapi.openapi.JSONAPIMarshmallowPlugin(schema_name_resolver=None)

Bases: MarshmallowPlugin

JSON:API Marshmallow plugin to handle JSONAPISchema subclasses.

Parameters

schema_name_resolver (Callable[[type[Schema]], str] | None) –

Converter

alias of JSONAPISchemaConverter

starlette_jsonapi.openapi.with_openapi_info(request_body=None, responses=None, include_in_schema=True, *args, **kwargs)

Decorates a handler to add OpenAPI information that will be merged (deep update) into the resource class information, overwriting common keys. Additional kwargs are included too, and the final dictionary will be used as the operation’s options.

Multiple with_openapi_info decorators can be used on the same handler.

Examples:

class ExampleResource(BaseResource):
    schema = ExampleSchema
    type_ = 'examples'

    @with_openapi_info(responses={'200': ExampleSchema, '404': ResourceNotFound})
    async def get(self, id: Any, *args, **kwargs) -> Response:
        # A 200 response body will be formed from ExampleSchema.
        # A 404 response body will be formed from the ResourceNotFound exception.

    @with_openapi_info(request_body=ExampleSchema)
    @with_openapi_info(summary='Updating an example')
    async def patch(self, id: Any, *args, **kwargs) -> Response:
        # A requestBody schema will be formed from ExampleSchema.
        # Summary for the path will be added as well.

    @with_openapi_info(include_in_schema=False)
    async def delete(self, id: Any, *args, **kwargs) -> Response:
        # Will not be registered in the OpenAPI specification.

    @with_openapi_info(responses={'200': ExampleSchema(many=True)})
    async def get_many(self, *args, **kwargs) -> Response:
        # A 200 response body will be formed from ExampleSchema, for a list of items.

Parameters

• request_body (Optional[Union[str, dict, JSONAPISchema, Type[JSONAPISchema]]]) – optional, a request body which will be required

• responses (Optional[Dict[str, Union[str, dict, JSONAPISchema, Type[JSONAPISchema], Exception, Type[Exception]]]]) – optional, a dictionary of HTTP status code -> response schema

• include_in_schema (bool) – Flag to control whether the handler is included in the OpenAPI spec

• args – Additional arguments, currently ignored

• kwargs – Additional keyword arguments, included in the operation’s options

Returns

The decorated handler

starlette_jsonapi.openapi.response_for_schema(schema)

Generates a response schema.

Parameters

schema (Union[str, dict, JSONAPISchema, Type[JSONAPISchema]]) –

Return type

dict

starlette_jsonapi.openapi.response_for_exception(exception, status_code)

Generates an exception schema.

Parameters

• exception (Union[Exception, Type[Exception]]) –

• status_code (str) –

Return type

dict

starlette_jsonapi.openapi.response_for_relationship(schema, relationship_name)

Generates a relationship response schema.

Examples:

class ExampleRelationshipResource(BaseRelationshipResource):
    parent_resource = ExampleResource
    relationship_name = 'rel'

    @with_openapi_info(
        responses={
            '200': response_for_relationship(ExampleResource.schema, relationship_name)
        }
    )
    async def get(self, parent_id: Any, *args, **kwargs) -> Response:
        # A 200 response body will be formed from the relationship
        # defined on parent resource schema.

Parameters

• schema (Union[JSONAPISchema, Type[JSONAPISchema]]) – the JSONAPISchema of the parent resource

• relationship_name (str) – the name of the relationship, as defined on the parent resource schema

Returns

The OpenAPI representation of the response

Return type

dict

starlette_jsonapi.openapi.request_for_relationship(schema, relationship_name)

Generates a relationship request schema.

Examples:

class ExampleRelationshipResource(BaseRelationshipResource):
    parent_resource = ExampleResource
    relationship_name = 'rel'

    @with_openapi_info(
        request_body=request_for_relationship(ExampleResource.schema, relationship_name)
    )
    async def post(self, parent_id: Any, *args, **kwargs) -> Response:
        # A request body will be formed from the relationship
        # defined on parent resource schema and marked as required.

Parameters

• schema (Union[JSONAPISchema, Type[JSONAPISchema]]) – the JSONAPISchema of the parent resource

• relationship_name (str) – the name of the relationship, as defined on the parent resource schema

Returns

The OpenAPI representation of the request

Return type

dict

starlette_jsonapi.openapi.request_for_schema(schema, method='post')

Generates a request schema.

Parameters

• schema (Union[str, dict, JSONAPISchema, Type[JSONAPISchema]]) –

• method (str) –

Return type

dict

class starlette_jsonapi.openapi.JSONAPISchemaGenerator(spec)

OpenAPI schema generator for JSON:API resources.

Parameters

spec (APISpec) –

__init__(spec)

Parameters

spec (APISpec) –

get_schema(routes)

Registers routes and their OpenAPI information in the apispec.APISpec.

Returns the OpenAPI specification for the given routes.

Parameters

routes (List[BaseRoute]) – List of registered routes

Returns

dict representation of the OpenAPI specification

Return type

dict