When using CUE for resource descriptions, comments on the cue fields are turned into OpenAPI "description" fields. This is great. I'd also like to use the "title" field if possible. Immediate use case is doing some form-and-display building automation for certain resource types. By supplying both a title and a description, it's easier to understand that "myComplicatedEnumTypeName" can just be "Order Status" in a UI. However, I think this is useful in general.
A few ways we could perhaps do this:
First line is the title. Not great because comment strings start to get unwieldy and maybe repetitive. Example with no description text:
{
// Order status
orderStatus: "unknown" | "cancelled" | "shipped" | "delivered"
}
with description:
{
// Order status
// The state of this order. This can only be set by a seller or fulfilment partner.
orderStatus: "unknown" | "cancelled" | "shipped" | "delivered"
}
We attempt to split and then sentence-case the name of the field, so "orderStatus" becomes "Order status" in the title.
This is a bit different from the way kubernetes does this, in that the base APIs don't supply a title, and they repeat the field name in the "description" field: "replicas is the number of currently active Pods in a Deployment" or similar.
(For solving my immediate use case I can also do something like ensure that the "description" string is parseable according to some simple standard I come up with, similar to this.)
When using CUE for resource descriptions, comments on the cue fields are turned into OpenAPI "description" fields. This is great. I'd also like to use the "title" field if possible. Immediate use case is doing some form-and-display building automation for certain resource types. By supplying both a title and a description, it's easier to understand that "myComplicatedEnumTypeName" can just be "Order Status" in a UI. However, I think this is useful in general.
A few ways we could perhaps do this:
with description:
This is a bit different from the way kubernetes does this, in that the base APIs don't supply a title, and they repeat the field name in the "description" field: "replicas is the number of currently active Pods in a Deployment" or similar.
(For solving my immediate use case I can also do something like ensure that the "description" string is parseable according to some simple standard I come up with, similar to this.)