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

[sjwl]

Discussed in https://github.com/cue-lang/cue/discussions/1127

^{Originally posted by **eadlam** July 21, 2021} 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?

[sjwl]

I took the liberty of creating an issue on behalf of OP, since we ran into this same issue.