OpenAPI: Include comments in description field of properties that point to a reference

[eadlam]

Consider this cue spec:

#Block: {
	// Name of the block
	name: string
	// min and max range for X
	xRange: #Range
	// min and max range for Y
	yRange: #Range
}

#Range: {
	// minimum value
	min: int
	// maximum value
	max: int
}

All of the properties have comments, and when we export OpenAPI specs most of these comments are added to the description field of the property. But, properties whose values are a $ref in OpenAPI (xRange, yRange) do not include the description:

{
    "openapi": "3.0.0",
    "info": {
        "title": "Generated by cue.",
        "version": "no version"
    },
    "paths": {},
    "components": {
        "schemas": {
            "Block": {
                "type": "object",
                "required": [
                    "name",
                    "xRange",
                    "yRange"
                ],
                "properties": {
                    "name": {
                        "description": "Name of the block",
                        "type": "string"
                    },
                    "xRange": {
                        "$ref": "#/components/schemas/Range"
                    },
                    "yRange": {
                        "$ref": "#/components/schemas/Range"
                    }
                }
            },
            "Range": {
                "type": "object",
                "required": [
                    "min",
                    "max"
                ],
                "properties": {
                    "min": {
                        "description": "minimum value",
                        "type": "integer"
                    },
                    "max": {
                        "description": "maximum value",
                        "type": "integer"
                    }
                }
            }
        }
    }
}

However, the OpenAPI 3.0 spec does not forbid a description as a sibling of a $ref, it only says that sibling properties will be ignored. See bottom of this page: https://swagger.io/docs/specification/using-ref/

I'm using these OpenAPI specs to generate code and documentation, and it would be very helpful to preserve comments in a description field sibling to the $ref. I don't think it would harm anything to have it there.

Thoughts?

[myitcv]

This seems entirely reasonable to me, not least because of the reference you cite (which also appears to have some background in json-schema-org/json-schema-spec#628 and friends) but also because the comment is associated with the field, rather than its type. Hence if we didn't support this I can't see how fields with this referenced type wouldn't end up with the same comment (i.e. the description attached to #Range, not that you have one here).

@eadlam please can you raise an issue for this? We can firm things up there. Thanks!

[sjwl]

@myitcv I created a link issue. We already use CUE to declare our order form schema for APIs, but now as we build human facing GUI, we need human friendly descriptions for each field, and want CUE to drive that too.