Repository: marshmallow-code/apispec

Issue:
Add support for `summary` and `description` fields for paths
Documented [here](https://swagger.io/docs/specification/paths-and-operations/):

> Paths may have an optional short summary and a longer description for documentation purposes. This information is supposed to be relevant to all operations in this path. description can be multi-line and supports Markdown (CommonMark) for rich text representation. 

Discussion:

Patch:
diff --git a/apispec/core.py b/apispec/core.py
index b3142e7..ddada9e 100644
--- a/apispec/core.py
+++ b/apispec/core.py
@@ -277,13 +277,17 @@ class APISpec(object):
         self._tags.append(tag)
         return self
 
-    def path(self, path=None, operations=None, **kwargs):
+    def path(
+        self, path=None, operations=None, summary=None, description=None, **kwargs
+    ):
         """Add a new path object to the spec.
 
         https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#path-item-object
 
         :param str|None path: URL path component
         :param dict|None operations: describes the http methods and options for `path`
+        :param str summary: short summary relevant to all operations in this path
+        :param str description: long description relevant to all operations in this path
         :param dict kwargs: parameters used by any path helpers see :meth:`register_path_helper`
         """
         operations = operations or OrderedDict()
@@ -309,4 +313,8 @@ class APISpec(object):
         clean_operations(operations, self.openapi_version.major)
 
         self._paths.setdefault(path, operations).update(operations)
+        if summary is not None:
+            self._paths[path]["summary"] = summary
+        if description is not None:
+            self._paths[path]["description"] = description
         return self


Test patch:
diff --git a/tests/test_core.py b/tests/test_core.py
index 594c035..cd13657 100644
--- a/tests/test_core.py
+++ b/tests/test_core.py
@@ -298,6 +298,15 @@ class TestPath:
             spec.path()
         assert "Path template is not specified" in str(excinfo)
 
+    def test_path_summary_description(self, spec):
+        summary = "Operations on a Pet"
+        description = "Operations on a Pet identified by its ID"
+        spec.path(path="/pet/{petId}", summary=summary, description=description)
+
+        p = get_paths(spec)["/pet/{petId}"]
+        assert p["summary"] == summary
+        assert p["description"] == description
+
     def test_parameter(self, spec):
         route_spec = self.paths["/pet/{petId}"]["get"]