blob: f26cff6e741edc9ecf93874554c5960d6f6519d1 [file] [log] [blame]
// Copyright 2019 CUE Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package openapi
import (
"encoding/json"
"fmt"
"strings"
"cuelang.org/go/cue"
"cuelang.org/go/cue/ast"
"cuelang.org/go/cue/errors"
"cuelang.org/go/cue/token"
cuejson "cuelang.org/go/encoding/json"
)
// A Config defines options for converting CUE to and from OpenAPI.
type Config struct {
// PkgName defines to package name for a generated CUE package.
PkgName string
// Info specifies the info section of the OpenAPI document. To be a valid
// OpenAPI document, it must include at least the title and version fields.
// Info may be a *ast.StructLit or any type that marshals to JSON.
Info interface{}
// ReferenceFunc allows users to specify an alternative representation
// for references. An empty string tells the generator to expand the type
// in place and, if applicable, not generate a schema for that entity.
ReferenceFunc func(inst *cue.Instance, path []string) string
// DescriptionFunc allows rewriting a description associated with a certain
// field. A typical implementation compiles the description from the
// comments obtains from the Doc method. No description field is added if
// the empty string is returned.
DescriptionFunc func(v cue.Value) string
// SelfContained causes all non-expanded external references to be included
// in this document.
SelfContained bool
// OpenAPI version to use. Supported as of v3.0.0.
Version string
// FieldFilter defines a regular expression of all fields to omit from the
// output. It is only allowed to filter fields that add additional
// constraints. Fields that indicate basic types cannot be removed. It is
// an error for such fields to be excluded by this filter.
// Fields are qualified by their Object type. For instance, the
// minimum field of the schema object is qualified as Schema/minimum.
FieldFilter string
// ExpandReferences replaces references with actual objects when generating
// OpenAPI Schema. It is an error for an CUE value to refer to itself
// if this option is used.
ExpandReferences bool
}
type Generator = Config
// Gen generates the set OpenAPI schema for all top-level types of the
// given instance.
func Gen(inst *cue.Instance, c *Config) ([]byte, error) {
if c == nil {
c = defaultConfig
}
all, err := c.All(inst)
if err != nil {
return nil, err
}
return json.Marshal(all)
}
// Generate generates the set of OpenAPI schema for all top-level types of the
// given instance.
//
// Note: only a limited number of top-level types are supported so far.
func Generate(inst *cue.Instance, c *Config) (*ast.File, error) {
all, err := schemas(c, inst)
if err != nil {
return nil, err
}
top, err := c.compose(inst, all)
if err != nil {
return nil, err
}
return &ast.File{Decls: top.Elts}, nil
}
// All generates an OpenAPI definition from the given instance.
//
// Note: only a limited number of top-level types are supported so far.
// Deprecated: use Generate
func (g *Generator) All(inst *cue.Instance) (*OrderedMap, error) {
all, err := schemas(g, inst)
if err != nil {
return nil, err
}
top, err := g.compose(inst, all)
return (*OrderedMap)(top), err
}
func toCUE(name string, x interface{}) (v ast.Expr, err error) {
b, err := json.Marshal(x)
if err == nil {
v, err = cuejson.Extract(name, b)
}
if err != nil {
return nil, errors.Wrapf(err, token.NoPos,
"openapi: could not encode %s", name)
}
return v, nil
}
func (c *Config) compose(inst *cue.Instance, schemas *ast.StructLit) (x *ast.StructLit, err error) {
var errs errors.Error
var title, version string
var info *ast.StructLit
for i, _ := inst.Value().Fields(cue.Definitions(true)); i.Next(); {
if !i.IsDefinition() {
label := i.Label()
attr := i.Value().Attribute("openapi")
if s, _ := attr.String(0); s != "" {
label = s
}
switch label {
case "-":
case "info":
info, _ = i.Value().Syntax().(*ast.StructLit)
if info == nil {
errs = errors.Append(errs, errors.Newf(i.Value().Pos(),
"info must be a struct"))
}
title, _ = i.Value().Lookup("title").String()
version, _ = i.Value().Lookup("version").String()
default:
errs = errors.Append(errs, errors.Newf(i.Value().Pos(),
"openapi: unsupported top-level field %q", x))
}
}
}
// Support of OrderedMap is mostly for backwards compatibility.
switch x := c.Info.(type) {
case nil:
if title == "" {
title = "Generated by cue."
for _, d := range inst.Doc() {
title = strings.TrimSpace(d.Text())
break
}
if p := inst.ImportPath; title == "" && p != "" {
title = fmt.Sprintf("Generated by cue from package %q", p)
}
}
if version == "" {
version, _ = inst.Lookup("$version").String()
if version == "" {
version = "no version"
}
}
if info == nil {
info = ast.NewStruct(
"title", ast.NewString(title),
"version", ast.NewString(version),
)
} else {
m := (*OrderedMap)(info)
m.Set("title", ast.NewString(title))
m.Set("version", ast.NewString(version))
}
case *ast.StructLit:
info = x
case *OrderedMap:
info = (*ast.StructLit)(x)
case OrderedMap:
info = (*ast.StructLit)(&x)
default:
x, err := toCUE("info section", x)
if err != nil {
return nil, err
}
info, _ = x.(*ast.StructLit)
errs = errors.Append(errs, errors.Newf(token.NoPos,
"Info field supplied must be an *ast.StructLit"))
}
return ast.NewStruct(
"openapi", ast.NewString(c.Version),
"info", info,
"paths", ast.NewStruct(),
"components", ast.NewStruct("schemas", schemas),
), nil
}
// Schemas extracts component/schemas from the CUE top-level types.
func (g *Generator) Schemas(inst *cue.Instance) (*OrderedMap, error) {
comps, err := schemas(g, inst)
if err != nil {
return nil, err
}
return (*OrderedMap)(comps), err
}
var defaultConfig = &Config{}
// TODO
// The conversion interprets @openapi(<entry> {, <entry>}) attributes as follows:
//
// readOnly sets the readOnly flag for a property in the schema
// only one of readOnly and writeOnly may be set.
// writeOnly sets the writeOnly flag for a property in the schema
// only one of readOnly and writeOnly may be set.
// discriminator explicitly sets a field as the discriminator field
//