Marcel van Lohuizen | f4d483e | 2019-05-20 08:03:10 -0400 | [diff] [blame] | 1 | // Copyright 2019 CUE Authors |
| 2 | // |
| 3 | // Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 | // you may not use this file except in compliance with the License. |
| 5 | // You may obtain a copy of the License at |
| 6 | // |
| 7 | // http://www.apache.org/licenses/LICENSE-2.0 |
| 8 | // |
| 9 | // Unless required by applicable law or agreed to in writing, software |
| 10 | // distributed under the License is distributed on an "AS IS" BASIS, |
| 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 | // See the License for the specific language governing permissions and |
| 13 | // limitations under the License. |
| 14 | |
| 15 | package openapi |
| 16 | |
| 17 | import ( |
| 18 | "encoding/json" |
Marcel van Lohuizen | 3c437bd | 2020-04-01 18:19:30 +0200 | [diff] [blame] | 19 | "fmt" |
| 20 | "strings" |
Marcel van Lohuizen | f4d483e | 2019-05-20 08:03:10 -0400 | [diff] [blame] | 21 | |
Marcel van Lohuizen | 845df05 | 2020-07-26 13:15:45 +0200 | [diff] [blame] | 22 | "cuelang.org/go/cue" |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 23 | "cuelang.org/go/cue/ast" |
| 24 | "cuelang.org/go/cue/errors" |
| 25 | "cuelang.org/go/cue/token" |
| 26 | cuejson "cuelang.org/go/encoding/json" |
Marcel van Lohuizen | f4d483e | 2019-05-20 08:03:10 -0400 | [diff] [blame] | 27 | ) |
| 28 | |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 29 | // A Config defines options for converting CUE to and from OpenAPI. |
| 30 | type Config struct { |
Marcel van Lohuizen | 64b39e6 | 2020-03-10 13:46:27 +0100 | [diff] [blame] | 31 | // PkgName defines to package name for a generated CUE package. |
| 32 | PkgName string |
| 33 | |
Marcel van Lohuizen | 4de93e1 | 2019-07-02 20:04:10 +0200 | [diff] [blame] | 34 | // Info specifies the info section of the OpenAPI document. To be a valid |
| 35 | // OpenAPI document, it must include at least the title and version fields. |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 36 | // Info may be a *ast.StructLit or any type that marshals to JSON. |
| 37 | Info interface{} |
Marcel van Lohuizen | 4de93e1 | 2019-07-02 20:04:10 +0200 | [diff] [blame] | 38 | |
Marcel van Lohuizen | ef90d5c | 2019-06-29 14:05:25 +0200 | [diff] [blame] | 39 | // ReferenceFunc allows users to specify an alternative representation |
Marcel van Lohuizen | ceb003d | 2019-08-08 13:45:10 +0200 | [diff] [blame] | 40 | // for references. An empty string tells the generator to expand the type |
Marcel van Lohuizen | 35abfa7 | 2019-08-12 15:31:53 +0200 | [diff] [blame] | 41 | // in place and, if applicable, not generate a schema for that entity. |
Marcel van Lohuizen | ef90d5c | 2019-06-29 14:05:25 +0200 | [diff] [blame] | 42 | ReferenceFunc func(inst *cue.Instance, path []string) string |
| 43 | |
Marcel van Lohuizen | 4de93e1 | 2019-07-02 20:04:10 +0200 | [diff] [blame] | 44 | // DescriptionFunc allows rewriting a description associated with a certain |
| 45 | // field. A typical implementation compiles the description from the |
| 46 | // comments obtains from the Doc method. No description field is added if |
| 47 | // the empty string is returned. |
| 48 | DescriptionFunc func(v cue.Value) string |
| 49 | |
Marcel van Lohuizen | ef90d5c | 2019-06-29 14:05:25 +0200 | [diff] [blame] | 50 | // SelfContained causes all non-expanded external references to be included |
| 51 | // in this document. |
| 52 | SelfContained bool |
| 53 | |
Marcel van Lohuizen | 2a8b4ed | 2020-06-16 09:21:44 +0200 | [diff] [blame] | 54 | // OpenAPI version to use. Supported as of v3.0.0. |
| 55 | Version string |
| 56 | |
Marcel van Lohuizen | 7b7ccdd | 2019-07-03 13:33:03 +0200 | [diff] [blame] | 57 | // FieldFilter defines a regular expression of all fields to omit from the |
| 58 | // output. It is only allowed to filter fields that add additional |
| 59 | // constraints. Fields that indicate basic types cannot be removed. It is |
| 60 | // an error for such fields to be excluded by this filter. |
| 61 | // Fields are qualified by their Object type. For instance, the |
| 62 | // minimum field of the schema object is qualified as Schema/minimum. |
| 63 | FieldFilter string |
| 64 | |
Marcel van Lohuizen | f4d483e | 2019-05-20 08:03:10 -0400 | [diff] [blame] | 65 | // ExpandReferences replaces references with actual objects when generating |
Marcel van Lohuizen | 73e3f6b | 2019-08-01 16:10:57 +0200 | [diff] [blame] | 66 | // OpenAPI Schema. It is an error for an CUE value to refer to itself |
| 67 | // if this option is used. |
Marcel van Lohuizen | f4d483e | 2019-05-20 08:03:10 -0400 | [diff] [blame] | 68 | ExpandReferences bool |
| 69 | } |
| 70 | |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 71 | type Generator = Config |
Marcel van Lohuizen | 865f159 | 2019-07-02 19:43:45 +0200 | [diff] [blame] | 72 | |
| 73 | // Gen generates the set OpenAPI schema for all top-level types of the |
| 74 | // given instance. |
Marcel van Lohuizen | f4d483e | 2019-05-20 08:03:10 -0400 | [diff] [blame] | 75 | func Gen(inst *cue.Instance, c *Config) ([]byte, error) { |
| 76 | if c == nil { |
| 77 | c = defaultConfig |
| 78 | } |
Marcel van Lohuizen | 865f159 | 2019-07-02 19:43:45 +0200 | [diff] [blame] | 79 | all, err := c.All(inst) |
Marcel van Lohuizen | f4d483e | 2019-05-20 08:03:10 -0400 | [diff] [blame] | 80 | if err != nil { |
| 81 | return nil, err |
| 82 | } |
Marcel van Lohuizen | 865f159 | 2019-07-02 19:43:45 +0200 | [diff] [blame] | 83 | return json.Marshal(all) |
| 84 | } |
| 85 | |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 86 | // Generate generates the set of OpenAPI schema for all top-level types of the |
| 87 | // given instance. |
Marcel van Lohuizen | 865f159 | 2019-07-02 19:43:45 +0200 | [diff] [blame] | 88 | // |
| 89 | // Note: only a limited number of top-level types are supported so far. |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 90 | func Generate(inst *cue.Instance, c *Config) (*ast.File, error) { |
| 91 | all, err := schemas(c, inst) |
Marcel van Lohuizen | 865f159 | 2019-07-02 19:43:45 +0200 | [diff] [blame] | 92 | if err != nil { |
| 93 | return nil, err |
| 94 | } |
Marcel van Lohuizen | 3c437bd | 2020-04-01 18:19:30 +0200 | [diff] [blame] | 95 | top, err := c.compose(inst, all) |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 96 | if err != nil { |
| 97 | return nil, err |
| 98 | } |
| 99 | return &ast.File{Decls: top.Elts}, nil |
| 100 | } |
Marcel van Lohuizen | 865f159 | 2019-07-02 19:43:45 +0200 | [diff] [blame] | 101 | |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 102 | // All generates an OpenAPI definition from the given instance. |
| 103 | // |
| 104 | // Note: only a limited number of top-level types are supported so far. |
| 105 | // Deprecated: use Generate |
| 106 | func (g *Generator) All(inst *cue.Instance) (*OrderedMap, error) { |
| 107 | all, err := schemas(g, inst) |
| 108 | if err != nil { |
| 109 | return nil, err |
| 110 | } |
Marcel van Lohuizen | 3c437bd | 2020-04-01 18:19:30 +0200 | [diff] [blame] | 111 | top, err := g.compose(inst, all) |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 112 | return (*OrderedMap)(top), err |
| 113 | } |
Marcel van Lohuizen | 865f159 | 2019-07-02 19:43:45 +0200 | [diff] [blame] | 114 | |
Marcel van Lohuizen | 5c2b086 | 2020-03-17 11:52:14 +0100 | [diff] [blame] | 115 | func toCUE(name string, x interface{}) (v ast.Expr, err error) { |
| 116 | b, err := json.Marshal(x) |
| 117 | if err == nil { |
| 118 | v, err = cuejson.Extract(name, b) |
| 119 | } |
| 120 | if err != nil { |
| 121 | return nil, errors.Wrapf(err, token.NoPos, |
| 122 | "openapi: could not encode %s", name) |
| 123 | } |
| 124 | return v, nil |
| 125 | |
| 126 | } |
| 127 | |
Marcel van Lohuizen | 3c437bd | 2020-04-01 18:19:30 +0200 | [diff] [blame] | 128 | func (c *Config) compose(inst *cue.Instance, schemas *ast.StructLit) (x *ast.StructLit, err error) { |
| 129 | |
| 130 | var errs errors.Error |
| 131 | |
| 132 | var title, version string |
| 133 | var info *ast.StructLit |
| 134 | |
| 135 | for i, _ := inst.Value().Fields(cue.Definitions(true)); i.Next(); { |
Daniel Martí | 4c10692 | 2020-08-18 21:49:52 +0200 | [diff] [blame] | 136 | if i.IsDefinition() { |
| 137 | continue |
| 138 | } |
| 139 | label := i.Label() |
| 140 | attr := i.Value().Attribute("openapi") |
| 141 | if s, _ := attr.String(0); s != "" { |
| 142 | label = s |
| 143 | } |
| 144 | switch label { |
| 145 | case "$version": |
| 146 | case "-": |
| 147 | case "info": |
| 148 | info, _ = i.Value().Syntax().(*ast.StructLit) |
| 149 | if info == nil { |
Marcel van Lohuizen | 3c437bd | 2020-04-01 18:19:30 +0200 | [diff] [blame] | 150 | errs = errors.Append(errs, errors.Newf(i.Value().Pos(), |
Daniel Martí | 4c10692 | 2020-08-18 21:49:52 +0200 | [diff] [blame] | 151 | "info must be a struct")) |
Marcel van Lohuizen | 3c437bd | 2020-04-01 18:19:30 +0200 | [diff] [blame] | 152 | } |
Daniel Martí | 4c10692 | 2020-08-18 21:49:52 +0200 | [diff] [blame] | 153 | title, _ = i.Value().Lookup("title").String() |
| 154 | version, _ = i.Value().Lookup("version").String() |
| 155 | |
| 156 | default: |
| 157 | errs = errors.Append(errs, errors.Newf(i.Value().Pos(), |
| 158 | "openapi: unsupported top-level field %q", label)) |
Marcel van Lohuizen | 3c437bd | 2020-04-01 18:19:30 +0200 | [diff] [blame] | 159 | } |
| 160 | } |
| 161 | |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 162 | // Support of OrderedMap is mostly for backwards compatibility. |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 163 | switch x := c.Info.(type) { |
| 164 | case nil: |
Marcel van Lohuizen | 3c437bd | 2020-04-01 18:19:30 +0200 | [diff] [blame] | 165 | if title == "" { |
| 166 | title = "Generated by cue." |
| 167 | for _, d := range inst.Doc() { |
| 168 | title = strings.TrimSpace(d.Text()) |
| 169 | break |
| 170 | } |
| 171 | if p := inst.ImportPath; title == "" && p != "" { |
| 172 | title = fmt.Sprintf("Generated by cue from package %q", p) |
| 173 | } |
| 174 | } |
| 175 | |
| 176 | if version == "" { |
| 177 | version, _ = inst.Lookup("$version").String() |
| 178 | if version == "" { |
| 179 | version = "no version" |
| 180 | } |
| 181 | } |
| 182 | |
| 183 | if info == nil { |
| 184 | info = ast.NewStruct( |
| 185 | "title", ast.NewString(title), |
| 186 | "version", ast.NewString(version), |
| 187 | ) |
| 188 | } else { |
| 189 | m := (*OrderedMap)(info) |
| 190 | m.Set("title", ast.NewString(title)) |
| 191 | m.Set("version", ast.NewString(version)) |
| 192 | } |
| 193 | |
| 194 | case *ast.StructLit: |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 195 | info = x |
| 196 | case *OrderedMap: |
| 197 | info = (*ast.StructLit)(x) |
| 198 | case OrderedMap: |
| 199 | info = (*ast.StructLit)(&x) |
| 200 | default: |
Marcel van Lohuizen | 3c437bd | 2020-04-01 18:19:30 +0200 | [diff] [blame] | 201 | x, err := toCUE("info section", x) |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 202 | if err != nil { |
Marcel van Lohuizen | 5c2b086 | 2020-03-17 11:52:14 +0100 | [diff] [blame] | 203 | return nil, err |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 204 | } |
Marcel van Lohuizen | 3c437bd | 2020-04-01 18:19:30 +0200 | [diff] [blame] | 205 | info, _ = x.(*ast.StructLit) |
| 206 | errs = errors.Append(errs, errors.Newf(token.NoPos, |
| 207 | "Info field supplied must be an *ast.StructLit")) |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 208 | } |
Marcel van Lohuizen | 865f159 | 2019-07-02 19:43:45 +0200 | [diff] [blame] | 209 | |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 210 | return ast.NewStruct( |
Marcel van Lohuizen | 2a8b4ed | 2020-06-16 09:21:44 +0200 | [diff] [blame] | 211 | "openapi", ast.NewString(c.Version), |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 212 | "info", info, |
| 213 | "paths", ast.NewStruct(), |
| 214 | "components", ast.NewStruct("schemas", schemas), |
Daniel Martí | 4c10692 | 2020-08-18 21:49:52 +0200 | [diff] [blame] | 215 | ), errs |
Marcel van Lohuizen | 865f159 | 2019-07-02 19:43:45 +0200 | [diff] [blame] | 216 | } |
| 217 | |
| 218 | // Schemas extracts component/schemas from the CUE top-level types. |
Marcel van Lohuizen | c89f5a6 | 2019-07-04 10:41:18 +0200 | [diff] [blame] | 219 | func (g *Generator) Schemas(inst *cue.Instance) (*OrderedMap, error) { |
Marcel van Lohuizen | 865f159 | 2019-07-02 19:43:45 +0200 | [diff] [blame] | 220 | comps, err := schemas(g, inst) |
| 221 | if err != nil { |
| 222 | return nil, err |
| 223 | } |
Marcel van Lohuizen | f51c879 | 2020-03-05 17:53:29 +0100 | [diff] [blame] | 224 | return (*OrderedMap)(comps), err |
Marcel van Lohuizen | f4d483e | 2019-05-20 08:03:10 -0400 | [diff] [blame] | 225 | } |
| 226 | |
| 227 | var defaultConfig = &Config{} |
| 228 | |
| 229 | // TODO |
| 230 | // The conversion interprets @openapi(<entry> {, <entry>}) attributes as follows: |
| 231 | // |
| 232 | // readOnly sets the readOnly flag for a property in the schema |
| 233 | // only one of readOnly and writeOnly may be set. |
| 234 | // writeOnly sets the writeOnly flag for a property in the schema |
| 235 | // only one of readOnly and writeOnly may be set. |
| 236 | // discriminator explicitly sets a field as the discriminator field |
Marcel van Lohuizen | f4d483e | 2019-05-20 08:03:10 -0400 | [diff] [blame] | 237 | // |