Added example support

Added tests
Completes a marshmallow-code#245 Todo

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>`_

src/apispec/core.py

@@ -30,12 +30,14 @@ def __init__(self, plugins, openapi_version):
         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 @@ def to_dict(self):
             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.
 

src/apispec/utils.py

@@ -17,6 +17,7 @@
         "security_scheme": "securityDefinitions",
     },
     3: {
+        "example": "examples",
         "schema": "schemas",
         "parameter": "parameters",
         "response": "responses",

tests/test_core.py

@@ -14,6 +14,7 @@
 
 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)

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"]