Discussions

There appears to be a bug in the way ReadMe is rendering descriptions of complex schemas that make use of allOf to combine multiple schema and reference objects.

The behavior that I'm seeing is the description within the most nested object is being used instead of the description from the top-level object.

Suppose your API spec is made up of two files, sampleSpec.json and common.json. Within those files you have the following sample schema objects defined:

 # Within sampleSpec.json:
			"Party": {
            "title": "Party",
            "description": "Information about a party",
            "allOf": [
                {
                    "$ref": "common.json#/components/schemas/NameAddress"
                },
                {
                    "type": "object",
                    "properties": {
                        "phone": {
                            "$ref": "common.json#/components/schemas/TelephoneNumber",
                            "description": "Phone number"
                        }
                    }
                },
                {
                    "type": "object",
                    "properties": {
                        "entityType": {
                            "$ref": "common.json#/components/schemas/EntityType"
                        }
                        "email": {
                            "type": "string",
                            "format": "email"
                        }
                    }
                }
            ],
            "type": "object"
        }

# Within common.json:
            "NameAddress": {
                "title": "Name and Address",
                "description": "Individual or business name with address",
                "required": [
                    "name1"
                ],                
                "allOf": [
                    {
                        "properties": {
                            "name1": {
                                "$ref": "#/components/schemas/String64",
                                "description": "Name line 1"
                            },
                            "name2": {
                                "$ref": "#/components/schemas/String64",
                                "description": "Name line 2"
                            }
                        },
                        "type": "object"
                    },
                    {
                        "$ref": "#/components/schemas/Address"
                    }
                ],
                "type": "object"
            },
            "Address": {
                "title": "Address",
                "description": "Postal address",
                "required": [
                    "line1",
                    "city",
                    "country"
                ],
                "properties": {
                    "line1": {
                        "type": "string",
                        "description": "Address line 1"
                    },
                    "line2": {
                        "type": "string",
                        "description": "Address line 2"
                    },
                    "line3": {
                        "type": "string",
                        "description": "Address line 3"
                    },
                    "city": {
                        "type": "string",
                        "description": "City"
                    },
                    "state": {
                        "type": "string",
                        "description": "State or province"
                    },
                    "postalCode": {
                        "type": "string",
                        "maxLength": 10,
                        "description": "Postal code"
                    },
                    "country": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/Iso3166CountryCode"
                            },
                            {
                                "type": "string",
                                "description": "Spelled-out country names -or- ISO 3166-2"
                            }
                        ],
                        "description": "Country"
                    }
                },
                "type": "object"
            },

When rendering the description for Party, I would expect to see Information about a party

However, ReadMe is rendering the text as Postal address.

This is in conflict with ReadMe's docs @ https://docs.readme.com/main/docs/openapi-compatibility-chart#reference-object:

Prior to rendering your API documentation all $ref pointers are dereferenced. Additionally, as of OpenAPI 3.1, you can include summary and description fields in addition to the $ref pointer, which will override the summary and description fields of the referenced component. Everything else will be fully dereferenced.