Add additionalProperties to includes' attributes and relationships (#1164)

Create new schema for objects in the included array

This allows documenting the "attributes" and "relationships" objects to
possibly have additional properties.

Author: arttuperala

CHANGELOG.md

@@ -43,6 +43,8 @@ any parts of the framework not mentioned in the documentation should generally b
 
 * `SerializerMethodResourceRelatedField(many=True)` relationship data now includes a meta section.
 * Required relationship fields are now marked as required in the OpenAPI schema.
+* Objects in the included array are documented in the OpenAPI schema to possibly have additional
+  properties in their "attributes" and "relationships" objects.
 
 ### Fixed
 

example/tests/__snapshots__/test_openapi.ambr

@@ -185,7 +185,7 @@
                 },
                 "included": {
                   "items": {
-                    "$ref": "#/components/schemas/resource"
+                    "$ref": "#/components/schemas/include"
                   },
                   "type": "array",
                   "uniqueItems": true
@@ -340,7 +340,7 @@
                 },
                 "included": {
                   "items": {
-                    "$ref": "#/components/schemas/resource"
+                    "$ref": "#/components/schemas/include"
                   },
                   "type": "array",
                   "uniqueItems": true
@@ -487,7 +487,7 @@
                 },
                 "included": {
                   "items": {
-                    "$ref": "#/components/schemas/resource"
+                    "$ref": "#/components/schemas/include"
                   },
                   "type": "array",
                   "uniqueItems": true
@@ -662,7 +662,7 @@
                 },
                 "included": {
                   "items": {
-                    "$ref": "#/components/schemas/resource"
+                    "$ref": "#/components/schemas/include"
                   },
                   "type": "array",
                   "uniqueItems": true
@@ -962,6 +962,36 @@
           "description": "Each resource object\u2019s type and id pair MUST [identify](https://jsonapi.org/format/#document-resource-object-identification) a single, unique resource.",
           "type": "string"
         },
+        "include": {
+          "additionalProperties": false,
+          "properties": {
+            "attributes": {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            "id": {
+              "$ref": "#/components/schemas/id"
+            },
+            "links": {
+              "$ref": "#/components/schemas/links"
+            },
+            "meta": {
+              "$ref": "#/components/schemas/meta"
+            },
+            "relationships": {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            "type": {
+              "$ref": "#/components/schemas/type"
+            }
+          },
+          "required": [
+            "type",
+            "id"
+          ],
+          "type": "object"
+        },
         "jsonapi": {
           "additionalProperties": false,
           "description": "The server's implementation",
@@ -1252,7 +1282,7 @@
                       },
                       "included": {
                         "items": {
-                          "$ref": "#/components/schemas/resource"
+                          "$ref": "#/components/schemas/include"
                         },
                         "type": "array",
                         "uniqueItems": true

rest_framework_json_api/schemas/openapi.py

@@ -49,6 +49,27 @@ class SchemaGenerator(drf_openapi.SchemaGenerator):
                     "meta": {"$ref": "#/components/schemas/meta"},
                 },
             },
+            "include": {
+                "type": "object",
+                "required": ["type", "id"],
+                "additionalProperties": False,
+                "properties": {
+                    "type": {"$ref": "#/components/schemas/type"},
+                    "id": {"$ref": "#/components/schemas/id"},
+                    "attributes": {
+                        "type": "object",
+                        "additionalProperties": True,
+                        # ...
+                    },
+                    "relationships": {
+                        "type": "object",
+                        "additionalProperties": True,
+                        # ...
+                    },
+                    "links": {"$ref": "#/components/schemas/links"},
+                    "meta": {"$ref": "#/components/schemas/meta"},
+                },
+            },
             "link": {
                 "oneOf": [
                     {
@@ -531,7 +552,7 @@ def _get_toplevel_200_response(self, operation, path, method, collection=True):
                             "included": {
                                 "type": "array",
                                 "uniqueItems": True,
-                                "items": {"$ref": "#/components/schemas/resource"},
+                                "items": {"$ref": "#/components/schemas/include"},
                             },
                             "links": {
                                 "description": "Link members related to primary data",