From 167a73ea89f6937c8fd61ae2d459e00f296fcccf Mon Sep 17 00:00:00 2001
From: Ashutosh <216.ashutosh@gmail.com>
Date: Mon, 4 Nov 2019 02:41:14 +0530
Subject: [PATCH] Added example support Added tests Completes a #245 Todo

---
 AUTHORS.rst          |  1 +
 src/apispec/core.py  | 17 +++++++++++++++++
 src/apispec/utils.py |  1 +
 tests/test_core.py   |  8 ++++++++
 tests/utils.py       |  4 ++++
 5 files changed, 31 insertions(+)

diff --git a/AUTHORS.rst b/AUTHORS.rst
index 7c480af5..d7234622 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 351d939d..f1b877d7 100644
--- a/src/apispec/core.py
+++ b/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.
 
diff --git a/src/apispec/utils.py b/src/apispec/utils.py
index 9657934b..7e413dc2 100644
--- a/src/apispec/utils.py
+++ b/src/apispec/utils.py
@@ -17,6 +17,7 @@
         "security_scheme": "securityDefinitions",
     },
     3: {
+        "example": "examples",
         "schema": "schemas",
         "parameter": "parameters",
         "response": "responses",
diff --git a/tests/test_core.py b/tests/test_core.py
index 4696a235..f6743d1f 100644
--- a/tests/test_core.py
+++ b/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)
diff --git a/tests/utils.py b/tests/utils.py
index 1a38df81..d7ed6253 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"]