OpenAPI and CRDs

How CUE integrates with OpenAPI, an API description format for REST.

OpenAPI is a standard for the description of REST APIs. Describing value schema is one aspect of this. In the Schema Definition section we already talked about the relationship between CUE and OpenAPI.

One aspect of OpenAPI is to define data schema. CUE supports converting CUE values to such schema. As CUE is more expressive than OpenAPI, it is not possible to generate a fully accurate OpenAPI schema. But CUE makes a best effort to encode as must as possible.

Generate OpenAPI

CUE currently only supports generating OpenAPI through its API. The Istio project has a command line tool to generate OpenAPI build on this API.

Generating an OpenAPI definition can be as simple as

import "cuelang.org/go/encoding/openapi"

func genOpenAPI(inst *cue.Instance) (b []byte, error) {
    b, err := openapi.Gen(inst, nil)
    if err != nil {
        return nil, err
    }

    var out = &bytes.Buffer{}
    _ = json.Indent(out, b, "", "   ")
    return out.Bytes(), nil
}

The cuelang.org/go/encoding/openapi package provides options to make a definition self-contained, expand references, filtering constraints, and so on.

If expanding references is selected it will ensure the output is in the Structural OpenAPI form, which is required for CRDs 1.15.

Last modified September 1, 2019: Update openapi.md (0afa558)