Repository: marshmallow-code/apispec
Pull request #515 (2019-11-03 21:14:06)

Add Components.example
Added tests
Completes a #245 Todo


Patch:
diff --git a/AUTHORS.rst b/AUTHORS.rst
index 7c480af..d723462 100644
--- a/AUTHORS.rst
+++ b/AUTHORS.rst
@@ -59,3 +59,4 @@ Contributors (chronological)
 - Dave `@zedrdave <https://github.com/zedrdave>`_
 - Emmanuel Valette `@karec <https://github.com/karec/>`_
 - Hugo van Kemenade `@hugovk <https://github.com/hugovk>`_
+- Ashutosh Chaudhary `@codeasashu <https://github.com/codeasashu>`_
diff --git a/src/apispec/core.py b/src/apispec/core.py
index 351d939..f1b877d 100644
--- a/src/apispec/core.py
+++ b/src/apispec/core.py
@@ -30,12 +30,14 @@ class Components:
         self._plugins = plugins
         self.openapi_version = openapi_version
         self._schemas = {}
+        self._examples = {}
         self._parameters = {}
         self._responses = {}
         self._security_schemes = {}
 
     def to_dict(self):
         subsections = {
+            "example": self._examples,
             "schema": self._schemas,
             "parameter": self._parameters,
             "response": self._responses,
@@ -47,6 +49,21 @@ class Components:
             if v != {}
         }
 
+    def example(self, name, component, **kwargs):
+        """Add an example which can be referenced
+
+        :param str name: identifier by which example may be referenced.
+        :param dict component: example fields.
+
+        https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#exampleObject
+        """
+        if name in self._examples:
+            raise DuplicateComponentNameError(
+                'Another example with name "{}" is already registered.'.format(name)
+            )
+        self._examples[name] = component
+        return self
+
     def schema(self, name, component=None, **kwargs):
         """Add a new schema to the spec.
 
diff --git a/src/apispec/utils.py b/src/apispec/utils.py
index 9657934..7e413dc 100644
--- a/src/apispec/utils.py
+++ b/src/apispec/utils.py
@@ -17,6 +17,7 @@ COMPONENT_SUBSECTIONS = {
         "security_scheme": "securityDefinitions",
     },
     3: {
+        "example": "examples",
         "schema": "schemas",
         "parameter": "parameters",
         "response": "responses",


Test patch:
diff --git a/tests/test_core.py b/tests/test_core.py
index 4696a23..f6743d1 100644
--- a/tests/test_core.py
+++ b/tests/test_core.py
@@ -14,6 +14,7 @@ from apispec.exceptions import (
 
 from .utils import (
     get_schemas,
+    get_examples,
     get_paths,
     get_parameters,
     get_responses,
@@ -137,6 +138,13 @@ class TestComponents:
         "name": {"type": "string", "example": "doggie"},
     }
 
+    # Referenced examples are only supported in OAS 3.x
+    @pytest.mark.parametrize("spec", ("3.0.0",), indirect=True)
+    def test_example(self, spec):
+        spec.components.example("PetExample", {"value": {"a": "b"}})
+        defs = get_examples(spec)
+        assert defs["PetExample"]["value"] == {"a": "b"}
+
     def test_schema(self, spec):
         spec.components.schema("Pet", {"properties": self.properties})
         defs = get_schemas(spec)
diff --git a/tests/utils.py b/tests/utils.py
index 1a38df8..d7ed625 100644
--- a/tests/utils.py
+++ b/tests/utils.py
@@ -3,6 +3,10 @@
 from apispec.utils import build_reference
 
 
+def get_examples(spec):
+    return spec.to_dict()["components"]["examples"]
+
+
 def get_schemas(spec):
     if spec.openapi_version.major < 3:
         return spec.to_dict()["definitions"]