/
types.go
415 lines (385 loc) · 11.5 KB
/
types.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
package openapiv3
import (
"encoding/binary"
"fmt"
"hash"
"hash/fnv"
"strconv"
"strings"
"goa.design/goa/codegen"
"goa.design/goa/expr"
"goa.design/goa/http/codegen/openapi"
)
type (
// EndpointBodies describes the request and response HTTP bodies of an endpoint
// using JSON schema. Each body may be described via a reference to a schema
// described in the "Components" section of the OpenAPI document or an actual
// JSON schema data structure. There may also be additional notes attached to
// each body definition to account for cases that are not directly supported in
// OpenAPI such as streaming. The possible response bodies are indexed by HTTP
// status, there may be more than one when the result type defined multiple
// views.
EndpointBodies struct {
RequestBody *openapi.Schema
ResponseBodies map[int][]*openapi.Schema
}
// schemafier is an internal data structure used to keep the state required to
// create JSON schemas for all the request and response body types.
schemafier struct {
// type schemas indexed by ref
schemas map[string]*openapi.Schema
// type names indexed by hashes
hashes map[uint64]string
rand *expr.Random
}
)
// newSchemafier initializes a schemafier.
func newSchemafier(rand *expr.Random) *schemafier {
return &schemafier{
schemas: make(map[string]*openapi.Schema),
hashes: make(map[uint64]string),
rand: rand,
}
}
// buildBodyTypes traverses the design and builds the JSON schemas that
// represent the request and response bodies of each endpoint. The algorithm
// also computes a good unique name for the different types making sure that two
// types that are actually identical share the same name. This is to handle
// properly the data structures created by the code generation algorithms which
// can duplicate types (for example if they are defined inline in the design).
// The result is a map of method details indexed by service name. Each method
// detail is in turn indexed by method name. The details contain JSON schema
// references and the actual JSON schemas are returned in the second result
// value indexed by type name.
//
// NOTE: entries are nil when the corresponding type is Empty.
func buildBodyTypes(api *expr.APIExpr) (map[string]map[string]*EndpointBodies, map[string]*openapi.Schema) {
bodies := make(map[string]map[string]*EndpointBodies)
sf := newSchemafier(api.Random())
for _, s := range api.HTTP.Services {
if !mustGenerate(s.Meta) || !mustGenerate(s.ServiceExpr.Meta) {
continue
}
sbodies := make(map[string]*EndpointBodies, len(s.HTTPEndpoints))
for _, e := range s.HTTPEndpoints {
if !mustGenerate(e.Meta) || !mustGenerate(e.MethodExpr.Meta) {
continue
}
req := sf.schemafy(e.Body)
if e.StreamingBody != nil {
sreq := sf.schemafy(e.StreamingBody)
var note string
if sreq.Ref != "" {
note = sreq.Ref
} else {
note = string(sreq.Type)
}
if req == nil {
req = sreq
if req.Description != "" {
req.Description += "\n"
}
req.Description += "Streaming body."
} else {
if req.Description != "" {
req.Description += "\n"
}
req.Description += fmt.Sprintf("Streaming body: %s", note)
}
}
res := make(map[int][]*openapi.Schema)
resps := e.Responses
for _, er := range e.HTTPErrors {
resps = append(resps, er.Response)
}
for _, resp := range resps {
var view string
if vs, ok := resp.Body.Meta["view"]; ok {
view = vs[0]
}
body := resp.Body
if view != "" {
// Static view
rt, err := expr.Project(body.Type.(*expr.ResultTypeExpr), view)
if err != nil { // bug
panic(fmt.Sprintf("failed to project %q to view %q", body.Type.Name(), view))
}
body.Type = rt
}
js := sf.schemafy(body)
if rt, ok := resp.Body.Type.(*expr.ResultTypeExpr); ok && js != nil {
if view == "" && rt.HasMultipleViews() {
// Dynamic views
if len(js.Description) > 0 {
js.Description += "\n"
}
js.Description += sf.viewsNote(rt)
}
}
res[resp.StatusCode] = append(res[resp.StatusCode], js)
}
sbodies[e.Name()] = &EndpointBodies{req, res}
}
bodies[s.Name()] = sbodies
}
return bodies, sf.schemas
}
func (sf *schemafier) schemafy(attr *expr.AttributeExpr) *openapi.Schema {
if attr.Type == expr.Empty {
return nil
}
s := openapi.NewSchema()
var note string
// Initialize type and format
switch t := attr.Type.(type) {
case expr.Primitive:
switch t.Kind() {
case expr.UIntKind, expr.UInt64Kind, expr.UInt32Kind:
s.Type = openapi.Type("integer")
case expr.IntKind, expr.Int64Kind:
s.Type = openapi.Type("integer")
s.Format = "int64"
case expr.Int32Kind:
s.Type = openapi.Type("integer")
s.Format = "int32"
case expr.Float32Kind:
s.Type = openapi.Type("number")
s.Format = "float"
case expr.Float64Kind:
s.Type = openapi.Type("number")
s.Format = "double"
case expr.BytesKind, expr.AnyKind:
s.Type = openapi.Type("string")
s.Format = "binary"
default:
s.Type = openapi.Type(t.Name())
}
case *expr.Array:
s.Type = openapi.Array
s.Items = sf.schemafy(t.ElemType)
case *expr.Object:
s.Type = openapi.Object
var itemNotes []string
for _, nat := range *t {
s.Properties[nat.Name] = sf.schemafy(nat.Attribute)
}
if len(itemNotes) > 0 {
note = strings.Join(itemNotes, "\n")
}
case *expr.Map:
s.Type = openapi.Object
s.AdditionalProperties = true
case expr.UserType:
h := sf.hashAttribute(attr, fnv.New64())
if ref, ok := sf.hashes[h]; ok {
s.Ref = ref
} else {
name := t.Name()
if n, ok := t.Attribute().Meta["name:original"]; ok {
name = n[0]
}
typeName := sf.uniquify(codegen.Goify(name, true))
s.Ref = toRef(typeName)
sf.hashes[h] = s.Ref
sf.schemas[typeName] = sf.schemafy(t.Attribute())
}
return s // All other schema properties are set in the reference
default:
panic(fmt.Sprintf("unknown type %T", t)) // bug
}
s.Description = attr.Description
if note != "" {
s.Description += "\n" + note
}
// Default value, example, extensions
s.DefaultValue = toStringMap(attr.DefaultValue)
s.Example = attr.Example(sf.rand)
s.Extensions = openapi.ExtensionsFromExpr(attr.Meta)
// Validations
val := attr.Validation
if val == nil {
return s
}
s.Enum = val.Values
s.Format = string(val.Format)
s.Pattern = val.Pattern
if val.Minimum != nil {
s.Minimum = val.Minimum
}
if val.Maximum != nil {
s.Maximum = val.Maximum
}
if val.MinLength != nil {
if _, ok := attr.Type.(*expr.Array); ok {
s.MinItems = val.MinLength
} else {
s.MinLength = val.MinLength
}
}
if val.MaxLength != nil {
if _, ok := attr.Type.(*expr.Array); ok {
s.MaxItems = val.MaxLength
} else {
s.MaxLength = val.MaxLength
}
}
s.Required = val.Required
return s
}
// uniquify returns n if n is not a known type name. Otherwise uniquify appends
// the smallest integer greater than 1 to n so the result is not a known type
// name.
func (sf *schemafier) uniquify(n string) string {
exists := func(n string) bool {
_, ok := sf.schemas[n]
return ok
}
i := 1
for exists(n) {
i++
n = strings.TrimRight(n, "0123456789") + strconv.Itoa(i)
}
return n
}
// viewsNote returns a human friendly description of the different possible
// response body shapes for the different views supported by the attribute type
// which must be a ResultType.
func (sf *schemafier) viewsNote(rt *expr.ResultTypeExpr) string {
var alts []string
for _, v := range rt.Views {
if v.Name != expr.DefaultView {
pr, err := expr.Project(rt, v.Name)
if err != nil {
panic(fmt.Sprintf("failed to project %q with view %q", rt.Name(), v.Name)) // bug, DSL should have performed validations
}
js := sf.schemafy(&expr.AttributeExpr{Type: pr})
alts = append(alts, js.Ref)
}
}
oneof := ""
last := ""
if len(alts) > 1 {
oneof = "one of "
last = " or " + alts[len(alts)-1]
alts = alts[:len(alts)-1]
}
return "Response body may alternatively be " + oneof + strings.Join(alts, ", ") + last
}
// toRef creates a relative JSON Schema reference from a type name that points
// to the corresponding definition in the OpenAPI "components" field.
func toRef(n string) string {
return fmt.Sprintf("#/components/schemas/%s", n)
}
// toStringMap converts map[interface{}]interface{} to a map[string]interface{}
// when possible.
func toStringMap(val interface{}) interface{} {
switch actual := val.(type) {
case map[interface{}]interface{}:
m := make(map[string]interface{})
for k, v := range actual {
m[toString(k)] = toStringMap(v)
}
return m
case []interface{}:
mapSlice := make([]interface{}, len(actual))
for i, e := range actual {
mapSlice[i] = toStringMap(e)
}
return mapSlice
default:
return actual
}
}
// toString returns the string representation of the given type.
func toString(val interface{}) string {
switch actual := val.(type) {
case string:
return actual
case int:
return strconv.Itoa(actual)
case float64:
return strconv.FormatFloat(actual, 'f', -1, 64)
case bool:
return strconv.FormatBool(actual)
default:
panic("unexpected key type")
}
}
// hashAttribute is helper function that computes a unique hash for the given
// attribute type. The algorithm returns the same value for two attributes whose
// types are structurally equivalent unless they are result types with different
// identifiers. Structurally identical means same primitive types, arrays with
// structurally equivalent element types, maps with structurally equivalent key
// and value types or object with identical attribute names and structurally
// equivalent types and identical set of required attributes.
func (sf *schemafier) hashAttribute(att *expr.AttributeExpr, h hash.Hash64) uint64 {
return *hashAttribute(att, h, make(map[string]*uint64))
}
func hashAttribute(att *expr.AttributeExpr, h hash.Hash64, seen map[string]*uint64) *uint64 {
t := att.Type
if h, ok := seen[t.Hash()]; ok {
return h
}
var res *uint64
{
var tmp uint64
res = &tmp
}
seen[t.Hash()] = res
switch t.Kind() {
case expr.ObjectKind:
o := expr.AsObject(t)
for _, m := range *o {
kh := hashString(m.Name, h)
vh := hashAttribute(m.Attribute, h, seen)
*res = *res ^ orderedHash(kh, *vh, h)
}
// Objects with a different set of required attributes should produce
// different hashes.
if att.Validation != nil {
for _, req := range att.Validation.Required {
rh := hashString(req, h)
*res = *res ^ rh
}
}
case expr.ArrayKind:
kh := hashString("[]", h)
vh := hashAttribute(expr.AsArray(t).ElemType, h, seen)
*res = orderedHash(kh, *vh, h)
case expr.MapKind:
m := expr.AsMap(t)
kh := hashAttribute(m.KeyType, h, seen)
vh := hashAttribute(m.ElemType, h, seen)
*res = orderedHash(*kh, *vh, h)
case expr.UserTypeKind:
*res = *hashAttribute(t.(expr.UserType).Attribute(), h, seen)
case expr.ResultTypeKind:
// The identifier specified in the design for result types should drive
// the computation of the hash.
rt := t.(*expr.ResultTypeExpr)
*res = hashString(rt.Identifier, h)
if view := rt.AttributeExpr.Meta["view"]; len(view) > 0 {
*res = orderedHash(*res, hashString(view[0], h), h)
}
default: // Primitives or Any
*res = hashString(t.Name(), h)
}
return res
}
func hashString(s string, h hash.Hash64) uint64 {
h.Reset()
if _, err := h.Write([]byte(s)); err != nil {
panic(err) // should not fail
}
return h.Sum64()
}
func orderedHash(a, b uint64, h hash.Hash64) uint64 {
h.Reset()
if err := binary.Write(h, binary.LittleEndian, a); err != nil {
panic(err) // should not fail
}
if err := binary.Write(h, binary.LittleEndian, b); err != nil {
panic(err) // should not fail
}
return h.Sum64()
}