forked from goadesign/goa
/
swagger.go
990 lines (918 loc) · 30.8 KB
/
swagger.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
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
package genswagger
import (
"fmt"
"sort"
"strconv"
"strings"
"github.com/goadesign/goa/design"
"github.com/goadesign/goa/dslengine"
"github.com/goadesign/goa/goagen/gen_schema"
)
type (
// Swagger represents an instance of a swagger object.
// See https://swagger.io/specification/
Swagger struct {
Swagger string `json:"swagger,omitempty"`
Info *Info `json:"info,omitempty"`
Host string `json:"host,omitempty"`
BasePath string `json:"basePath,omitempty"`
Schemes []string `json:"schemes,omitempty"`
Consumes []string `json:"consumes,omitempty"`
Produces []string `json:"produces,omitempty"`
Paths map[string]*Path `json:"paths"`
Definitions map[string]*genschema.JSONSchema `json:"definitions,omitempty"`
Parameters map[string]*Parameter `json:"parameters,omitempty"`
Responses map[string]*Response `json:"responses,omitempty"`
SecurityDefinitions map[string]*SecurityDefinition `json:"securityDefinitions,omitempty"`
Tags []*Tag `json:"tags,omitempty"`
ExternalDocs *ExternalDocs `json:"externalDocs,omitempty"`
}
// Info provides metadata about the API. The metadata can be used by the clients if needed,
// and can be presented in the Swagger-UI for convenience.
Info struct {
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
TermsOfService string `json:"termsOfService,omitempty"`
Contact *design.ContactDefinition `json:"contact,omitempty"`
License *design.LicenseDefinition `json:"license,omitempty"`
Version string `json:"version"`
}
// Path holds the relative paths to the individual endpoints.
Path struct {
// Ref allows for an external definition of this path item.
Ref string `json:"$ref,omitempty"`
// Get defines a GET operation on this path.
Get *Operation `json:"get,omitempty"`
// Put defines a PUT operation on this path.
Put *Operation `json:"put,omitempty"`
// Post defines a POST operation on this path.
Post *Operation `json:"post,omitempty"`
// Delete defines a DELETE operation on this path.
Delete *Operation `json:"delete,omitempty"`
// Options defines a OPTIONS operation on this path.
Options *Operation `json:"options,omitempty"`
// Head defines a HEAD operation on this path.
Head *Operation `json:"head,omitempty"`
// Patch defines a PATCH operation on this path.
Patch *Operation `json:"patch,omitempty"`
// Parameters is the list of parameters that are applicable for all the operations
// described under this path.
Parameters []*Parameter `json:"parameters,omitempty"`
}
// Operation describes a single API operation on a path.
Operation struct {
// Tags is a list of tags for API documentation control. Tags can be used for
// logical grouping of operations by resources or any other qualifier.
Tags []string `json:"tags,omitempty"`
// Summary is a short summary of what the operation does. For maximum readability
// in the swagger-ui, this field should be less than 120 characters.
Summary string `json:"summary,omitempty"`
// Description is a verbose explanation of the operation behavior.
// GFM syntax can be used for rich text representation.
Description string `json:"description,omitempty"`
// ExternalDocs points to additional external documentation for this operation.
ExternalDocs *ExternalDocs `json:"externalDocs,omitempty"`
// OperationID is a unique string used to identify the operation.
OperationID string `json:"operationId,omitempty"`
// Consumes is a list of MIME types the operation can consume.
Consumes []string `json:"consumes,omitempty"`
// Produces is a list of MIME types the operation can produce.
Produces []string `json:"produces,omitempty"`
// Parameters is a list of parameters that are applicable for this operation.
Parameters []*Parameter `json:"parameters,omitempty"`
// Responses is the list of possible responses as they are returned from executing
// this operation.
Responses map[string]*Response `json:"responses,omitempty"`
// Schemes is the transfer protocol for the operation.
Schemes []string `json:"schemes,omitempty"`
// Deprecated declares this operation to be deprecated.
Deprecated bool `json:"deprecated,omitempty"`
// Secury is a declaration of which security schemes are applied for this operation.
Security []map[string][]string `json:"security,omitempty"`
}
// Parameter describes a single operation parameter.
Parameter struct {
// Name of the parameter. Parameter names are case sensitive.
Name string `json:"name"`
// In is the location of the parameter.
// Possible values are "query", "header", "path", "formData" or "body".
In string `json:"in"`
// Description is`a brief description of the parameter.
// GFM syntax can be used for rich text representation.
Description string `json:"description,omitempty"`
// Required determines whether this parameter is mandatory.
Required bool `json:"required"`
// Schema defining the type used for the body parameter, only if "in" is body
Schema *genschema.JSONSchema `json:"schema,omitempty"`
// properties below only apply if "in" is not body
// Type of the parameter. Since the parameter is not located at the request body,
// it is limited to simple types (that is, not an object).
Type string `json:"type,omitempty"`
// Format is the extending format for the previously mentioned type.
Format string `json:"format,omitempty"`
// AllowEmptyValue sets the ability to pass empty-valued parameters.
// This is valid only for either query or formData parameters and allows you to
// send a parameter with a name only or an empty value. Default value is false.
AllowEmptyValue bool `json:"allowEmptyValue,omitempty"`
// Items describes the type of items in the array if type is "array".
Items *Items `json:"items,omitempty"`
// CollectionFormat determines the format of the array if type array is used.
// Possible values are csv, ssv, tsv, pipes and multi.
CollectionFormat string `json:"collectionFormat,omitempty"`
// Default declares the value of the parameter that the server will use if none is
// provided, for example a "count" to control the number of results per page might
// default to 100 if not supplied by the client in the request.
Default interface{} `json:"default,omitempty"`
Maximum *float64 `json:"maximum,omitempty"`
ExclusiveMaximum bool `json:"exclusiveMaximum,omitempty"`
Minimum *float64 `json:"minimum,omitempty"`
ExclusiveMinimum bool `json:"exclusiveMinimum,omitempty"`
MaxLength *int `json:"maxLength,omitempty"`
MinLength *int `json:"minLength,omitempty"`
Pattern string `json:"pattern,omitempty"`
MaxItems *int `json:"maxItems,omitempty"`
MinItems *int `json:"minItems,omitempty"`
UniqueItems bool `json:"uniqueItems,omitempty"`
Enum []interface{} `json:"enum,omitempty"`
MultipleOf float64 `json:"multipleOf,omitempty"`
}
// Response describes an operation response.
Response struct {
// Description of the response. GFM syntax can be used for rich text representation.
Description string `json:"description,omitempty"`
// Schema is a definition of the response structure. It can be a primitive,
// an array or an object. If this field does not exist, it means no content is
// returned as part of the response. As an extension to the Schema Object, its root
// type value may also be "file".
Schema *genschema.JSONSchema `json:"schema,omitempty"`
// Headers is a list of headers that are sent with the response.
Headers map[string]*Header `json:"headers,omitempty"`
// Ref references a global API response.
// This field is exclusive with the other fields of Response.
Ref string `json:"$ref,omitempty"`
}
// Header represents a header parameter.
Header struct {
// Description is`a brief description of the parameter.
// GFM syntax can be used for rich text representation.
Description string `json:"description,omitempty"`
// Type of the header. it is limited to simple types (that is, not an object).
Type string `json:"type,omitempty"`
// Format is the extending format for the previously mentioned type.
Format string `json:"format,omitempty"`
// Items describes the type of items in the array if type is "array".
Items *Items `json:"items,omitempty"`
// CollectionFormat determines the format of the array if type array is used.
// Possible values are csv, ssv, tsv, pipes and multi.
CollectionFormat string `json:"collectionFormat,omitempty"`
// Default declares the value of the parameter that the server will use if none is
// provided, for example a "count" to control the number of results per page might
// default to 100 if not supplied by the client in the request.
Default interface{} `json:"default,omitempty"`
Maximum *float64 `json:"maximum,omitempty"`
ExclusiveMaximum bool `json:"exclusiveMaximum,omitempty"`
Minimum *float64 `json:"minimum,omitempty"`
ExclusiveMinimum bool `json:"exclusiveMinimum,omitempty"`
MaxLength *int `json:"maxLength,omitempty"`
MinLength *int `json:"minLength,omitempty"`
Pattern string `json:"pattern,omitempty"`
MaxItems *int `json:"maxItems,omitempty"`
MinItems *int `json:"minItems,omitempty"`
UniqueItems bool `json:"uniqueItems,omitempty"`
Enum []interface{} `json:"enum,omitempty"`
MultipleOf float64 `json:"multipleOf,omitempty"`
}
// SecurityDefinition allows the definition of a security scheme that can be used by the
// operations. Supported schemes are basic authentication, an API key (either as a header or
// as a query parameter) and OAuth2's common flows (implicit, password, application and
// access code).
SecurityDefinition struct {
// Type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".
Type string `json:"type"`
// Description for security scheme
Description string `json:"description,omitempty"`
// Name of the header or query parameter to be used when type is "apiKey".
Name string `json:"name,omitempty"`
// In is the location of the API key when type is "apiKey".
// Valid values are "query" or "header".
In string `json:"in,omitempty"`
// Flow is the flow used by the OAuth2 security scheme when type is "oauth2"
// Valid values are "implicit", "password", "application" or "accessCode".
Flow string `json:"flow,omitempty"`
// The oauth2 authorization URL to be used for this flow.
AuthorizationURL string `json:"authorizationUrl,omitempty"`
// TokenURL is the token URL to be used for this flow.
TokenURL string `json:"tokenUrl,omitempty"`
// Scopes list the available scopes for the OAuth2 security scheme.
Scopes map[string]string `json:"scopes,omitempty"`
}
// Scope corresponds to an available scope for an OAuth2 security scheme.
Scope struct {
// Description for scope
Description string `json:"description,omitempty"`
}
// ExternalDocs allows referencing an external resource for extended documentation.
ExternalDocs struct {
// Description is a short description of the target documentation.
// GFM syntax can be used for rich text representation.
Description string `json:"description,omitempty"`
// URL for the target documentation.
URL string `json:"url"`
}
// Items is a limited subset of JSON-Schema's items object. It is used by parameter
// definitions that are not located in "body".
Items struct {
// Type of the items. it is limited to simple types (that is, not an object).
Type string `json:"type,omitempty"`
// Format is the extending format for the previously mentioned type.
Format string `json:"format,omitempty"`
// Items describes the type of items in the array if type is "array".
Items *Items `json:"items,omitempty"`
// CollectionFormat determines the format of the array if type array is used.
// Possible values are csv, ssv, tsv, pipes and multi.
CollectionFormat string `json:"collectionFormat,omitempty"`
// Default declares the value of the parameter that the server will use if none is
// provided, for example a "count" to control the number of results per page might
// default to 100 if not supplied by the client in the request.
Default interface{} `json:"default,omitempty"`
Maximum *float64 `json:"maximum,omitempty"`
ExclusiveMaximum bool `json:"exclusiveMaximum,omitempty"`
Minimum *float64 `json:"minimum,omitempty"`
ExclusiveMinimum bool `json:"exclusiveMinimum,omitempty"`
MaxLength *int `json:"maxLength,omitempty"`
MinLength *int `json:"minLength,omitempty"`
Pattern string `json:"pattern,omitempty"`
MaxItems *int `json:"maxItems,omitempty"`
MinItems *int `json:"minItems,omitempty"`
UniqueItems bool `json:"uniqueItems,omitempty"`
Enum []interface{} `json:"enum,omitempty"`
MultipleOf float64 `json:"multipleOf,omitempty"`
}
// Tag allows adding meta data to a single tag that is used by the Operation Object. It is
// not mandatory to have a Tag Object per tag used there.
Tag struct {
// Name of the tag.
Name string `json:"name,omitempty"`
// Description is a short description of the tag.
// GFM syntax can be used for rich text representation.
Description string `json:"description,omitempty"`
// ExternalDocs is additional external documentation for this tag.
ExternalDocs *ExternalDocs `json:"externalDocs,omitempty"`
}
)
// New creates a Swagger spec from an API definition.
func New(api *design.APIDefinition) (*Swagger, error) {
if api == nil {
return nil, nil
}
tags := tagsFromDefinition(api.Metadata)
basePath := api.BasePath
if hasAbsoluteRoutes(api) {
basePath = ""
}
params, err := paramsFromDefinition(api.Params, basePath)
if err != nil {
return nil, err
}
var paramMap map[string]*Parameter
if len(params) > 0 {
paramMap = make(map[string]*Parameter, len(params))
for _, p := range params {
paramMap[p.Name] = p
}
}
var consumes []string
for _, c := range api.Consumes {
consumes = append(consumes, c.MIMETypes...)
}
var produces []string
for _, p := range api.Produces {
produces = append(produces, p.MIMETypes...)
}
s := &Swagger{
Swagger: "2.0",
Info: &Info{
Title: api.Title,
Description: api.Description,
TermsOfService: api.TermsOfService,
Contact: api.Contact,
License: api.License,
Version: api.Version,
},
Host: api.Host,
BasePath: basePath,
Paths: make(map[string]*Path),
Schemes: api.Schemes,
Consumes: consumes,
Produces: produces,
Parameters: paramMap,
Tags: tags,
ExternalDocs: docsFromDefinition(api.Docs),
SecurityDefinitions: securityDefsFromDefinition(api.SecuritySchemes),
}
err = api.IterateResponses(func(r *design.ResponseDefinition) error {
res, err := responseSpecFromDefinition(s, api, r)
if err != nil {
return err
}
if s.Responses == nil {
s.Responses = make(map[string]*Response)
}
s.Responses[r.Name] = res
return nil
})
if err != nil {
return nil, err
}
err = api.IterateResources(func(res *design.ResourceDefinition) error {
err := res.IterateFileServers(func(fs *design.FileServerDefinition) error {
return buildPathFromFileServer(s, api, fs)
})
if err != nil {
return err
}
return res.IterateActions(func(a *design.ActionDefinition) error {
for _, route := range a.Routes {
if err := buildPathFromDefinition(s, api, route, basePath); err != nil {
return err
}
}
return nil
})
})
if err != nil {
return nil, err
}
if len(genschema.Definitions) > 0 {
s.Definitions = make(map[string]*genschema.JSONSchema)
for n, d := range genschema.Definitions {
// sad but swagger doesn't support these
d.Media = nil
d.Links = nil
s.Definitions[n] = d
}
}
return s, nil
}
// hasAbsoluteRoutes returns true if any action exposed by the API uses an absolute route of if the
// API has file servers. This is needed as Swagger does not support exceptions to the base path so
// if the API has any absolute route the base path must be "/" and all routes must be absolutes.
func hasAbsoluteRoutes(api *design.APIDefinition) bool {
hasAbsoluteRoutes := false
for _, res := range api.Resources {
if len(res.FileServers) > 0 {
hasAbsoluteRoutes = true
break
}
for _, a := range res.Actions {
for _, ro := range a.Routes {
if ro.IsAbsolute() {
hasAbsoluteRoutes = true
break
}
}
if hasAbsoluteRoutes {
break
}
}
if hasAbsoluteRoutes {
break
}
}
return hasAbsoluteRoutes
}
func securityDefsFromDefinition(schemes []*design.SecuritySchemeDefinition) map[string]*SecurityDefinition {
if len(schemes) == 0 {
return nil
}
defs := make(map[string]*SecurityDefinition)
for _, scheme := range schemes {
def := &SecurityDefinition{
Type: scheme.Type,
Description: scheme.Description,
Name: scheme.Name,
In: scheme.In,
Flow: scheme.Flow,
AuthorizationURL: scheme.AuthorizationURL,
TokenURL: scheme.TokenURL,
Scopes: scheme.Scopes,
}
if scheme.Kind == design.JWTSecurityKind {
if def.TokenURL != "" {
def.Description += fmt.Sprintf("\n\n**Token URL**: %s", def.TokenURL)
def.TokenURL = ""
}
if len(def.Scopes) != 0 {
def.Description += fmt.Sprintf("\n\n**Security Scopes**:\n%s", scopesMapList(def.Scopes))
def.Scopes = nil
}
}
defs[scheme.SchemeName] = def
}
return defs
}
func scopesMapList(scopes map[string]string) string {
names := []string{}
for name := range scopes {
names = append(names, name)
}
sort.Strings(names)
lines := []string{}
for _, name := range names {
lines = append(lines, fmt.Sprintf(" * `%s`: %s", name, scopes[name]))
}
return strings.Join(lines, "\n")
}
func tagsFromDefinition(mdata dslengine.MetadataDefinition) (tags []*Tag) {
for key, value := range mdata {
chunks := strings.Split(key, ":")
if len(chunks) != 3 {
continue
}
if chunks[0] != "swagger" && chunks[1] != "tag" {
continue
}
tag := &Tag{Name: chunks[2]}
value = mdata[fmt.Sprintf("%s:desc", key)]
if len(value) != 0 {
tag.Description = value[0]
}
hasDocs := false
docs := &ExternalDocs{}
value = mdata[fmt.Sprintf("%s:url", key)]
if len(value) != 0 {
docs.URL = value[0]
hasDocs = true
}
value = mdata[fmt.Sprintf("%s:url:desc", key)]
if len(value) != 0 {
docs.Description = value[0]
hasDocs = true
}
if hasDocs {
tag.ExternalDocs = docs
}
tags = append(tags, tag)
}
return
}
func tagNamesFromDefinitions(mdatas ...dslengine.MetadataDefinition) (tagNames []string) {
for _, mdata := range mdatas {
tags := tagsFromDefinition(mdata)
for _, tag := range tags {
tagNames = append(tagNames, tag.Name)
}
}
return
}
func summaryFromDefinition(name string, metadata dslengine.MetadataDefinition) string {
for n, mdata := range metadata {
if n == "swagger:summary" && len(mdata) > 0 {
return mdata[0]
}
}
return name
}
func paramsFromDefinition(params *design.AttributeDefinition, path string) ([]*Parameter, error) {
if params == nil {
return nil, nil
}
obj := params.Type.ToObject()
if obj == nil {
return nil, fmt.Errorf("invalid parameters definition, not an object")
}
res := make([]*Parameter, len(obj))
i := 0
wildcards := design.ExtractWildcards(path)
obj.IterateAttributes(func(n string, at *design.AttributeDefinition) error {
in := "query"
required := params.IsRequired(n)
for _, w := range wildcards {
if n == w {
in = "path"
required = true
break
}
}
param := paramFor(at, n, in, required)
res[i] = param
i++
return nil
})
return res, nil
}
func paramsFromHeaders(action *design.ActionDefinition) []*Parameter {
params := []*Parameter{}
action.IterateHeaders(func(name string, required bool, header *design.AttributeDefinition) error {
p := paramFor(header, name, "header", required)
params = append(params, p)
return nil
})
return params
}
func paramFor(at *design.AttributeDefinition, name, in string, required bool) *Parameter {
p := &Parameter{
In: in,
Name: name,
Default: toStringMap(at.DefaultValue),
Description: at.Description,
Required: required,
Type: at.Type.Name(),
}
if at.Type.IsArray() {
p.Items = itemsFromDefinition(at.Type.ToArray().ElemType)
}
initValidations(at, p)
return p
}
// 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")
}
}
func itemsFromDefinition(at *design.AttributeDefinition) *Items {
items := &Items{Type: at.Type.Name()}
initValidations(at, items)
if at.Type.IsArray() {
items.Items = itemsFromDefinition(at.Type.ToArray().ElemType)
}
return items
}
func responseSpecFromDefinition(s *Swagger, api *design.APIDefinition, r *design.ResponseDefinition) (*Response, error) {
var schema *genschema.JSONSchema
if r.MediaType != "" {
if mt, ok := api.MediaTypes[design.CanonicalIdentifier(r.MediaType)]; ok {
schema = genschema.TypeSchema(api, mt)
}
}
headers, err := headersFromDefinition(r.Headers)
if err != nil {
return nil, err
}
return &Response{
Description: r.Description,
Schema: schema,
Headers: headers,
}, nil
}
func responseFromDefinition(s *Swagger, api *design.APIDefinition, r *design.ResponseDefinition) (*Response, error) {
var (
response *Response
err error
)
response, err = responseSpecFromDefinition(s, api, r)
if err != nil {
return nil, err
}
if r.Standard {
if s.Responses == nil {
s.Responses = make(map[string]*Response)
}
if _, ok := s.Responses[r.Name]; !ok {
sp, err := responseSpecFromDefinition(s, api, r)
if err != nil {
return nil, err
}
s.Responses[r.Name] = sp
}
}
return response, nil
}
func headersFromDefinition(headers *design.AttributeDefinition) (map[string]*Header, error) {
if headers == nil {
return nil, nil
}
obj := headers.Type.ToObject()
if obj == nil {
return nil, fmt.Errorf("invalid headers definition, not an object")
}
res := make(map[string]*Header)
obj.IterateAttributes(func(n string, at *design.AttributeDefinition) error {
header := &Header{
Default: at.DefaultValue,
Description: at.Description,
Type: at.Type.Name(),
}
initValidations(at, header)
res[n] = header
return nil
})
return res, nil
}
func buildPathFromFileServer(s *Swagger, api *design.APIDefinition, fs *design.FileServerDefinition) error {
wcs := design.ExtractWildcards(fs.RequestPath)
var param []*Parameter
if len(wcs) > 0 {
param = []*Parameter{{
In: "path",
Name: wcs[0],
Description: "Relative file path",
Required: true,
Type: "string",
}}
}
responses := map[string]*Response{
"200": {
Description: "File downloaded",
Schema: &genschema.JSONSchema{Type: genschema.JSONFile},
},
}
if len(wcs) > 0 {
schema := genschema.TypeSchema(api, design.ErrorMedia)
responses["404"] = &Response{Description: "File not found", Schema: schema}
}
operationID := fmt.Sprintf("%s#%s", fs.Parent.Name, fs.RequestPath)
schemes := api.Schemes
operation := &Operation{
Description: fs.Description,
Summary: summaryFromDefinition(fmt.Sprintf("Download %s", fs.FilePath), fs.Metadata),
ExternalDocs: docsFromDefinition(fs.Docs),
OperationID: operationID,
Parameters: param,
Responses: responses,
Schemes: schemes,
}
applySecurity(operation, fs.Security)
key := design.WildcardRegex.ReplaceAllStringFunc(
fs.RequestPath,
func(w string) string {
return fmt.Sprintf("/{%s}", w[2:])
},
)
if key == "" {
key = "/"
}
var path *Path
var ok bool
if path, ok = s.Paths[key]; !ok {
path = new(Path)
s.Paths[key] = path
}
path.Get = operation
return nil
}
func buildPathFromDefinition(s *Swagger, api *design.APIDefinition, route *design.RouteDefinition, basePath string) error {
action := route.Parent
tagNames := tagNamesFromDefinitions(action.Parent.Metadata, action.Metadata)
if len(tagNames) == 0 {
// By default tag with resource name
tagNames = []string{route.Parent.Parent.Name}
}
params, err := paramsFromDefinition(action.AllParams(), route.FullPath())
if err != nil {
return err
}
params = append(params, paramsFromHeaders(action)...)
responses := make(map[string]*Response, len(action.Responses))
for _, r := range action.Responses {
resp, err := responseFromDefinition(s, api, r)
if err != nil {
return err
}
responses[strconv.Itoa(r.Status)] = resp
}
if action.Payload != nil {
payloadSchema := genschema.TypeSchema(api, action.Payload)
pp := &Parameter{
Name: "payload",
In: "body",
Description: action.Payload.Description,
Required: true,
Schema: payloadSchema,
}
params = append(params, pp)
}
operationID := fmt.Sprintf("%s#%s", action.Parent.Name, action.Name)
index := 0
for i, rt := range action.Routes {
if rt == route {
index = i
break
}
}
if index > 0 {
operationID = fmt.Sprintf("%s#%d", operationID, index)
}
schemes := action.Schemes
if len(schemes) == 0 {
schemes = api.Schemes
}
operation := &Operation{
Tags: tagNames,
Description: action.Description,
Summary: summaryFromDefinition(action.Name+" "+action.Parent.Name, action.Metadata),
ExternalDocs: docsFromDefinition(action.Docs),
OperationID: operationID,
Parameters: params,
Responses: responses,
Schemes: schemes,
Deprecated: false,
}
applySecurity(operation, action.Security)
key := design.WildcardRegex.ReplaceAllStringFunc(
route.FullPath(),
func(w string) string {
return fmt.Sprintf("/{%s}", w[2:])
},
)
if key == "" {
key = "/"
}
bp := design.WildcardRegex.ReplaceAllStringFunc(
basePath,
func(w string) string {
return fmt.Sprintf("/{%s}", w[2:])
},
)
key = strings.TrimPrefix(key, bp)
var path *Path
var ok bool
if path, ok = s.Paths[key]; !ok {
path = new(Path)
s.Paths[key] = path
}
switch route.Verb {
case "GET":
path.Get = operation
case "PUT":
path.Put = operation
case "POST":
path.Post = operation
case "DELETE":
path.Delete = operation
case "OPTIONS":
path.Options = operation
case "HEAD":
path.Head = operation
case "PATCH":
path.Patch = operation
}
return nil
}
func applySecurity(operation *Operation, security *design.SecurityDefinition) {
if security != nil && security.Scheme.Kind != design.NoSecurityKind {
if security.Scheme.Kind == design.JWTSecurityKind {
if operation.Description != "" {
operation.Description += "\n\n"
}
operation.Description += fmt.Sprintf("Required security scopes:\n%s", scopesList(security.Scopes))
}
scopes := security.Scopes
if scopes == nil {
scopes = make([]string, 0)
}
sec := []map[string][]string{{security.Scheme.SchemeName: scopes}}
operation.Security = sec
}
}
func scopesList(scopes []string) string {
sort.Strings(scopes)
var lines []string
for _, scope := range scopes {
lines = append(lines, fmt.Sprintf(" * `%s`", scope))
}
return strings.Join(lines, "\n")
}
func docsFromDefinition(docs *design.DocsDefinition) *ExternalDocs {
if docs == nil {
return nil
}
return &ExternalDocs{
Description: docs.Description,
URL: docs.URL,
}
}
func initEnumValidation(def interface{}, values []interface{}) {
switch actual := def.(type) {
case *Parameter:
actual.Enum = values
case *Header:
actual.Enum = values
case *Items:
actual.Enum = values
}
}
func initFormatValidation(def interface{}, format string) {
switch actual := def.(type) {
case *Parameter:
actual.Format = format
case *Header:
actual.Format = format
case *Items:
actual.Format = format
}
}
func initPatternValidation(def interface{}, pattern string) {
switch actual := def.(type) {
case *Parameter:
actual.Pattern = pattern
case *Header:
actual.Pattern = pattern
case *Items:
actual.Pattern = pattern
}
}
func initMinimumValidation(def interface{}, min *float64) {
switch actual := def.(type) {
case *Parameter:
actual.Minimum = min
actual.ExclusiveMinimum = false
case *Header:
actual.Minimum = min
actual.ExclusiveMinimum = false
case *Items:
actual.Minimum = min
actual.ExclusiveMinimum = false
}
}
func initMaximumValidation(def interface{}, max *float64) {
switch actual := def.(type) {
case *Parameter:
actual.Maximum = max
actual.ExclusiveMaximum = false
case *Header:
actual.Maximum = max
actual.ExclusiveMaximum = false
case *Items:
actual.Maximum = max
actual.ExclusiveMaximum = false
}
}
func initMinLengthValidation(def interface{}, isArray bool, min *int) {
switch actual := def.(type) {
case *Parameter:
if isArray {
actual.MinItems = min
} else {
actual.MinLength = min
}
case *Header:
actual.MinLength = min
case *Items:
actual.MinLength = min
}
}
func initMaxLengthValidation(def interface{}, isArray bool, max *int) {
switch actual := def.(type) {
case *Parameter:
if isArray {
actual.MaxItems = max
} else {
actual.MaxLength = max
}
case *Header:
actual.MaxLength = max
case *Items:
actual.MaxLength = max
}
}
func initValidations(attr *design.AttributeDefinition, def interface{}) {
val := attr.Validation
if val == nil {
return
}
initEnumValidation(def, val.Values)
initFormatValidation(def, val.Format)
initPatternValidation(def, val.Pattern)
if val.Minimum != nil {
initMinimumValidation(def, val.Minimum)
}
if val.Maximum != nil {
initMaximumValidation(def, val.Maximum)
}
if val.MinLength != nil {
initMinLengthValidation(def, attr.Type.IsArray(), val.MinLength)
}
if val.MaxLength != nil {
initMaxLengthValidation(def, attr.Type.IsArray(), val.MaxLength)
}
}