CUE does not import "example:" fields from openapi spec

[obernil]

What version of CUE are you using (cue version)?

$ cue version
cue version v0.4.1 linux/amd64

Does this issue reproduce with the latest release?

yes

What did you do?

cue import openapi3sample.yaml

(see openapi3sample.yaml for full gist)

-- openapi3sample.yaml --

...
components:
  schemas:
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
          example: 18446744073709551614
        name:
          type: string
        tag:
          type: string
...

What did you expect to see?

-- openapi3sample.cue --

// Swagger Petstore

info: {
    version: *"1.0.0" | string
    title:   *"Swagger Petstore" | string
    license: name: "MIT"
}

#Pet: null | bool | number | string | [...] | {
    //example id: 18446744073709551614
    id:   int
    name: string
    tag?: string
    ...
}
#Pets: [...#Pet]
#Error: null | bool | number | string | [...] | {
    code:    int
    message: string
    ...
}

What did you see instead?

-- openapi3sample.cue --

// Swagger Petstore

info: {
    version: *"1.0.0" | string
    title:   *"Swagger Petstore" | string
    license: name: "MIT"
}

#Pet: null | bool | number | string | [...] | {
    id:   int
    name: string
    tag?: string
    ...
}
#Pets: [...#Pet]
#Error: null | bool | number | string | [...] | {
    code:    int
    message: string
    ...
}

[rogpeppe]

@obernil Thanks for the report. To be clear, it seems like this is asking for a new feature: that examples in the OpenAPI schema are imported as comments containing the example. I wonder if the translation should also work the other way around: that specially formatted comments should be exported as examples to OpenAPI. ISTM that this needs some design thought.

[obernil]

@rogpeppe thanks

I thought it was something OOTB as the same functionality is present elsewhere (I don't recall exactly where in the docs ATM).

For sure it would make like a good addition as having examples as comments is way more readable than having some nested json/yaml field.

And yes, I'd implement it as a two way thing.

For the CUE comment -> OpenAPI example translation I don't know what a good format would be.

Maybe something lightweight like starting with //-- or even //EX or just unambiguous //example (really just throwing ideas here).

I don't know if there are other constraints language wise though.