Omit include parameter from OpenAPI schema when left unused (#1157)

Author: arttuperala

CHANGELOG.md

@@ -20,6 +20,8 @@ any parts of the framework not mentioned in the documentation should generally b
 * Added support to overwrite serializer methods in customized schema class
 * Adjusted some still old formatted strings to f-strings.
 * Replaced `OrderedDict` with `dict` which is also ordered since Python 3.7.
+* Compound document "include" parameter is only included in the OpenAPI schema if serializer
+  implements `included_serializers`.
 
 ### Fixed
 

example/tests/test_openapi.py

@@ -110,6 +110,22 @@ def test_schema_construction(snapshot):
     assert snapshot == json.dumps(schema, indent=2, sort_keys=True)
 
 
+def test_schema_parameters_include():
+    """Include paramater is only used when serializer defines included_serializers."""
+    patterns = [
+        re_path("^authors/?$", views.AuthorViewSet.as_view({"get": "list"})),
+        re_path("^project-types/?$", views.ProjectTypeViewset.as_view({"get": "list"})),
+    ]
+    generator = SchemaGenerator(patterns=patterns)
+
+    request = create_request("/")
+    schema = generator.get_schema(request=request)
+
+    include_ref = {"$ref": "#/components/parameters/include"}
+    assert include_ref in schema["paths"]["/authors/"]["get"]["parameters"]
+    assert include_ref not in schema["paths"]["/project-types/"]["get"]["parameters"]
+
+
 def test_schema_related_serializers():
     """
     Confirm that paths are generated for related fields. For example:

rest_framework_json_api/schemas/openapi.py

@@ -406,11 +406,13 @@ def get_operation(self, path, method):
         operation["operationId"] = self.get_operation_id(path, method)
         operation["description"] = self.get_description(path, method)
 
+        serializer = self.get_response_serializer(path, method)
+
         parameters = []
         parameters += self.get_path_parameters(path, method)
         # pagination, filters only apply to GET/HEAD of collections and items
         if method in ["GET", "HEAD"]:
-            parameters += self._get_include_parameters(path, method)
+            parameters += self._get_include_parameters(path, method, serializer)
             parameters += self._get_fields_parameters(path, method)
             parameters += self.get_pagination_parameters(path, method)
             parameters += self.get_filter_parameters(path, method)
@@ -448,11 +450,13 @@ def get_operation_id(self, path, method):
             action = self.method_mapping[method.lower()]
         return action + path
 
-    def _get_include_parameters(self, path, method):
+    def _get_include_parameters(self, path, method, serializer):
         """
         includes parameter: https://jsonapi.org/format/#fetching-includes
         """
-        return [{"$ref": "#/components/parameters/include"}]
+        if getattr(serializer, "included_serializers", {}):
+            return [{"$ref": "#/components/parameters/include"}]
+        return []
 
     def _get_fields_parameters(self, path, method):
         """