Generates invalid schema. Use allOf when a description is added to a $ref

[nateguchi]

When generating the OpenAPI schema, properties with JSDoc comments that are not simple types will create invalid JSON.

Code:

OpenAPI JSON:

"DogResponse": {
	"properties": {
		"currentMembership": {
			"$ref": "#/components/schemas/MembershipResponse",
			"description": "The current active membership of the dog."
		}
    }
}

$refs cannot have other properties. So the description is overwritten.

If you had several properties sharing the same type, this will cause ambiguity e.g. currentMembership pastMembership

the correct output should be:

"DogResponse": {
	"properties": {
		"currentMembership": {
			"allOf":[
				{
					"$ref": "#/components/schemas/MembershipResponse",
				}
			],			
			"description": "The current active membership of the dog."
		}
    }
}

[github-actions[bot]]

Hello there nateguchi 👋

Thank you for opening your very first issue in this project.

We will try to get back to you as soon as we can.👀

[philsturgeon]

Won't need to worry about that with OAS 3.1. #1813