Add callback component (#245)

Add support for OpenAPI v3 callback components:
- Register callback in COMPONENT_SUBSECTIONS for OpenAPI v3.
- Add Components.callback() for registering reusable callbacks.
- Support lazy registration and resolution of referenced callbacks in operations.
- Add callback_helper to BasePlugin and MarshmallowPlugin.
- Add test coverage and validation against OpenAPI schema.

Author: ansh-rohilla

CHANGELOG.rst

@@ -4,6 +4,10 @@ Changelog
 unreleased
 **********
 
+Features:
+
+- Add ``callback`` component (:issue:`245`).
+
 Bug fixes:
 
 - Recognize ``trace`` operations defined in view docstrings, instead of

src/apispec/core.py

@@ -53,12 +53,14 @@ def __init__(
         self.examples: dict[str, dict] = {}
         self.links: dict[str, dict] = {}
         self.security_schemes: dict[str, dict] = {}
+        self.callbacks: dict[str, dict] = {}
         self.schemas_lazy: dict[str, dict] = {}
         self.responses_lazy: dict[str, dict] = {}
         self.parameters_lazy: dict[str, dict] = {}
         self.headers_lazy: dict[str, dict] = {}
         self.examples_lazy: dict[str, dict] = {}
         self.links_lazy: dict[str, dict] = {}
+        self.callbacks_lazy: dict[str, dict] = {}
 
         self._subsections = {
             "schema": self.schemas,
@@ -68,6 +70,7 @@ def __init__(
             "example": self.examples,
             "link": self.links,
             "security_scheme": self.security_schemes,
+            "callback": self.callbacks,
         }
         self._subsections_lazy = {
             "schema": self.schemas_lazy,
@@ -76,6 +79,7 @@ def __init__(
             "header": self.headers_lazy,
             "example": self.examples_lazy,
             "link": self.links_lazy,
+            "callback": self.callbacks_lazy,
         }
 
     def to_dict(self) -> dict[str, dict]:
@@ -329,6 +333,38 @@ def security_scheme(self, component_id: str, component: dict) -> Components:
         self._register_component("security_scheme", component_id, component)
         return self
 
+    def callback(
+        self,
+        component_id: str,
+        component: dict | None = None,
+        *,
+        lazy: bool = False,
+        **kwargs: typing.Any,
+    ) -> Components:
+        """Add a callback which can be referenced.
+
+        :param str component_id: identifier by which callback may be referenced
+        :param dict component: callback fields
+        :param bool lazy: register component only when referenced in the spec
+        :param kwargs: plugin-specific arguments
+
+        https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#callbackObject
+        """
+        if component_id in self.callbacks:
+            raise DuplicateComponentNameError(
+                f'Another callback with name "{component_id}" is already registered.'
+            )
+        ret = deepcopy(component) or {}
+        # Execute all helpers from plugins
+        for plugin in self._plugins:
+            try:
+                ret.update(plugin.callback_helper(ret, **kwargs) or {})
+            except PluginMethodNotImplementedError:
+                continue
+        self._resolve_refs_in_callback(ret)
+        self._register_component("callback", component_id, ret, lazy=lazy)
+        return self
+
     def _resolve_schema(self, obj) -> None:
         """Replace schema reference as string with a $ref if needed
 
@@ -375,6 +411,13 @@ def _resolve_refs_in_request_body(self, request_body) -> None:
             self._resolve_schema(media_type)
             self._resolve_examples(media_type)
 
+    def _resolve_refs_in_callback(self, callback) -> None:
+        # callback is OpenAPI v3+
+        if "$ref" not in callback:
+            for path in callback.values():
+                if isinstance(path, dict):
+                    self.resolve_refs_in_path(path)
+
     def _resolve_refs_in_response(self, response) -> None:
         if self.openapi_version.major < 3:
             self._resolve_schema(response)
@@ -397,10 +440,12 @@ def _resolve_refs_in_operation(self, operation) -> None:
                 parameters.append(parameter)
             operation["parameters"] = parameters
         if "callbacks" in operation:
-            for callback in operation["callbacks"].values():
-                if isinstance(callback, dict):
-                    for path in callback.values():
-                        self.resolve_refs_in_path(path)
+            callbacks = {}
+            for name, callback in operation["callbacks"].items():
+                callback = self.get_ref("callback", callback)
+                self._resolve_refs_in_callback(callback)
+                callbacks[name] = callback
+            operation["callbacks"] = callbacks
         if "requestBody" in operation:
             self._resolve_refs_in_request_body(operation["requestBody"])
         if "responses" in operation:

src/apispec/ext/marshmallow/__init__.py

@@ -222,6 +222,16 @@ def header_helper(self, header: dict, **kwargs: typing.Any):
         self.resolver.resolve_schema(header)
         return header
 
+    def callback_helper(self, callback: dict, **kwargs: typing.Any):
+        """Callback component helper that allows using a marshmallow
+        :class:`Schema <marshmallow.Schema>` in callback definition.
+
+        :param dict callback: callback fields.
+        """
+        assert self.resolver  # needed for mypy
+        self.resolver.resolve_callback({"": callback})
+        return callback
+
     def operation_helper(
         self,
         path: str | None = None,

src/apispec/ext/marshmallow/schema_resolver.py

@@ -75,9 +75,10 @@ def resolve_callback(self, callbacks):
 
         """
         for callback in callbacks.values():
-            if isinstance(callback, dict):
+            if isinstance(callback, dict) and "$ref" not in callback:
                 for path in callback.values():
-                    self.resolve_operations(path)
+                    if isinstance(path, dict):
+                        self.resolve_operations(path)
 
     def resolve_parameters(self, parameters):
         """Resolve marshmallow Schemas in a list of OpenAPI `Parameter Objects

src/apispec/plugin.py

@@ -36,6 +36,14 @@ def response_helper(self, response: dict, **kwargs: typing.Any) -> dict | None:
         """
         raise PluginMethodNotImplementedError
 
+    def callback_helper(self, callback: dict, **kwargs: typing.Any) -> dict | None:
+        """May return callback component description as a dict.
+
+        :param dict callback: Callback fields
+        :param kwargs: All additional keywords arguments sent to `APISpec.callback()`
+        """
+        raise PluginMethodNotImplementedError
+
     def parameter_helper(self, parameter: dict, **kwargs: typing.Any) -> dict | None:
         """May return parameter component description as a dict.
 

src/apispec/utils.py

@@ -21,6 +21,7 @@
         "example": "examples",
         "link": "links",
         "security_scheme": "securitySchemes",
+        "callback": "callbacks",
     },
 }
 
@@ -30,7 +31,7 @@ def build_reference(
 ) -> dict[str, str]:
     """Return path to reference
 
-    :param str component_type: Component type (schema, parameter, response, security_scheme)
+    :param str component_type: Component type (schema, parameter, response, security_scheme, callback)
     :param int openapi_major_version: OpenAPI major version (2 or 3)
     :param str component_name: Name of component to reference
     """

tests/test_core.py

@@ -14,6 +14,7 @@
 
 from .utils import (
     build_ref,
+    get_callbacks,
     get_examples,
     get_headers,
     get_links,
@@ -22,6 +23,7 @@
     get_responses,
     get_schemas,
     get_security_schemes,
+    validate_spec,
 )
 
 description = "This is a sample Petstore server.  You can find out more "
@@ -359,6 +361,40 @@ def test_links_duplicate_name(self, spec):
         with pytest.raises(APISpecError, match='Another link with name "GetUser"'):
             spec.components.link("GetUser", link)
 
+    @pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
+    def test_callbacks(self, spec):
+        callback = {
+            "{$request.query.callbackUrl}": {
+                "post": {
+                    "requestBody": {
+                        "content": {"application/json": {"schema": {"type": "string"}}}
+                    },
+                    "responses": {"200": {"description": "callback received"}},
+                }
+            }
+        }
+        spec.components.callback("myCallback", callback)
+        callbacks = get_callbacks(spec)
+        assert "myCallback" in callbacks
+        assert callbacks["myCallback"] == callback
+        assert validate_spec(spec)
+
+    @pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
+    def test_callback_is_chainable(self, spec):
+        spec.components.callback("cb1", {}).callback("cb2", {})
+        callbacks = get_callbacks(spec)
+        assert "cb1" in callbacks
+        assert "cb2" in callbacks
+
+    @pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
+    def test_callback_duplicate_name(self, spec):
+        spec.components.callback("myCallback", {})
+        with pytest.raises(
+            DuplicateComponentNameError,
+            match='Another callback with name "myCallback" is already registered.',
+        ):
+            spec.components.callback("myCallback", {})
+
     def test_security_scheme(self, spec):
         sec_scheme = {"type": "apiKey", "in": "header", "name": "X-API-Key"}
         spec.components.security_scheme("ApiKeyAuth", sec_scheme)
@@ -642,6 +678,62 @@ def test_links_lazy(self, spec):
         assert "GetUser" in links
         assert links["GetUser"] == link
 
+    # "callbacks" components section only exists in OAS 3
+    @pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
+    def test_components_resolve_refs_in_callback(self, spec):
+        callback = {
+            "{$request.query.callbackUrl}": {
+                "post": {
+                    "parameters": [
+                        {"name": "param", "in": "query", "schema": "ParamSchema"}
+                    ],
+                    "requestBody": {
+                        "content": {"application/json": {"schema": "BodySchema"}}
+                    },
+                    "responses": {"200": {"description": "OK"}},
+                }
+            }
+        }
+        spec.components.callback("myCallback", callback)
+        resolved_cb = get_callbacks(spec)["myCallback"]
+        op = resolved_cb["{$request.query.callbackUrl}"]["post"]
+        assert op["parameters"][0]["schema"] == build_ref(spec, "schema", "ParamSchema")
+        assert op["requestBody"]["content"]["application/json"]["schema"] == build_ref(
+            spec, "schema", "BodySchema"
+        )
+
+    # Referenced callbacks are only supported in OAS 3.x
+    @pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
+    def test_callbacks_lazy(self, spec):
+        callback = {
+            "{$request.query.callbackUrl}": {
+                "post": {
+                    "responses": {"200": {"description": "OK"}},
+                }
+            }
+        }
+        spec.components.callback("Callback_1", callback, lazy=False)
+        spec.components.callback("Callback_2", callback, lazy=True)
+        callbacks = get_callbacks(spec)
+        assert "Callback_1" in callbacks
+        assert "Callback_2" not in callbacks
+        spec.path(
+            "/path",
+            operations={
+                "post": {
+                    "callbacks": {"myCallback": "Callback_2"},
+                    "responses": {"200": {"description": "OK"}},
+                }
+            },
+        )
+        callbacks = get_callbacks(spec)
+        assert "Callback_2" in callbacks
+        post_op = spec.to_dict()["paths"]["/path"]["post"]
+        assert post_op["callbacks"]["myCallback"] == build_ref(
+            spec, "callback", "Callback_2"
+        )
+        assert validate_spec(spec)
+
 
 class TestPath(RefsSchemaTestMixin):
     paths = {
@@ -987,6 +1079,23 @@ def test_path_resolve_callbacks(self, spec):
             == schema_ref
         )
 
+    # callbacks only exists in OAS 3
+    @pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
+    def test_path_resolve_callback_ref(self, spec):
+        spec.path(
+            "/pet/{petId}",
+            operations={
+                "get": {
+                    "callbacks": {
+                        "onEvent": "EventCallback",
+                    }
+                }
+            },
+        )
+        assert get_paths(spec)["/pet/{petId}"]["get"]["callbacks"][
+            "onEvent"
+        ] == build_ref(spec, "callback", "EventCallback")
+
     # requestBody only exists in OAS 3
     @pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
     def test_path_resolve_request_body(self, spec):
@@ -1139,6 +1248,11 @@ def header_helper(self, header, **kwargs):
                 if not return_none:
                     return {"description": "some header"}
 
+            def callback_helper(self, callback, **kwargs):
+                callback.pop("dummy", None)
+                if not return_none:
+                    return {"description": "some callback"}
+
             def path_helper(self, path, operations, parameters, **kwargs):
                 if not return_none:
                     if path == "/path_1":
@@ -1234,6 +1348,27 @@ def test_plugin_header_helper_is_used(self, openapi_version, return_none):
         # Check original header is not modified
         assert header == {"dummy": "dummy"}
 
+    @pytest.mark.parametrize("openapi_version", ("3.0.0",))
+    @pytest.mark.parametrize("return_none", (True, False))
+    def test_plugin_callback_helper_is_used(self, openapi_version, return_none):
+        spec = APISpec(
+            title="Swagger Petstore",
+            version="1.0.0",
+            openapi_version=openapi_version,
+            plugins=(self.make_test_plugin(return_none),),
+        )
+        callback = {"dummy": "dummy"}
+        spec.components.callback("myCallback", callback)
+        callbacks = get_callbacks(spec)
+        if return_none:
+            assert callbacks["myCallback"] == {}
+        else:
+            assert callbacks["myCallback"] == {
+                "description": "some callback",
+            }
+        # Check original callback is not modified
+        assert callback == {"dummy": "dummy"}
+
     @pytest.mark.parametrize("openapi_version", ("2.0", "3.0.0"))
     @pytest.mark.parametrize("return_none", (True, False))
     def test_plugin_path_helper_is_used(self, openapi_version, return_none):

tests/test_ext_marshmallow.py

@@ -31,6 +31,7 @@
 )
 from .utils import (
     build_ref,
+    get_callbacks,
     get_headers,
     get_parameters,
     get_paths,
@@ -317,6 +318,33 @@ def test_can_use_schema_in_header(self, spec, schema):
         assert resolved_schema["properties"]["id"]["type"] == "integer"
 
 
+class TestComponentCallbackHelper:
+    @pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
+    @pytest.mark.parametrize("schema", [PetSchema, PetSchema()])
+    def test_can_use_schema_in_callback(self, spec, schema):
+        cb = {
+            "{$request.query.callbackUrl}": {
+                "post": {
+                    "requestBody": {
+                        "content": {"application/json": {"schema": schema}}
+                    },
+                    "responses": {"200": {"description": "success"}},
+                }
+            }
+        }
+        spec.components.callback("myCallback", cb)
+        resolved_cb = get_callbacks(spec)["myCallback"]
+        reference = resolved_cb["{$request.query.callbackUrl}"]["post"]["requestBody"][
+            "content"
+        ]["application/json"]["schema"]
+        assert reference == build_ref(spec, "schema", "Pet")
+
+        resolved_schema = spec.components.schemas["Pet"]
+        assert resolved_schema["properties"]["name"]["type"] == "string"
+        assert resolved_schema["properties"]["password"]["type"] == "string"
+        assert resolved_schema["properties"]["id"]["type"] == "integer"
+
+
 class TestCustomField:
     def test_can_use_custom_field_decorator(self, spec_fixture):
         class CustomNameA(Field):