1// Copyright 2015 go-swagger maintainers
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
15package analysis
16
17import (
18	"fmt"
19	"reflect"
20
21	"github.com/go-openapi/spec"
22)
23
24// Mixin modifies the primary swagger spec by adding the paths and
25// definitions from the mixin specs. Top level parameters and
26// responses from the mixins are also carried over. Operation id
27// collisions are avoided by appending "Mixin<N>" but only if
28// needed.
29//
30// The following parts of primary are never modified by merging:
31//   - Info
32//   - BasePath
33//   - Host
34//   - ExternalDocs
35//
36// Consider calling FixEmptyResponseDescriptions() on the modified primary
37// if you read them from storage and they are valid to start with.
38//
39// Entries in "paths", "definitions", "parameters" and "responses" are
40// added to the primary in the order of the given mixins. If the entry
41// already exists in primary it is skipped with a warning message.
42//
43// The count of skipped entries (from collisions) is returned so any
44// deviation from the number expected can flag a warning in your build
45// scripts. Carefully review the collisions before accepting them;
46// consider renaming things if possible.
47//
48// No key normalization takes place (paths, type defs,
49// etc). Ensure they are canonical if your downstream tools do
50// key normalization of any form.
51//
52// Merging schemes (http, https), and consumers/producers do not account for
53// collisions.
54func Mixin(primary *spec.Swagger, mixins ...*spec.Swagger) []string {
55	skipped := make([]string, 0, len(mixins))
56	opIds := getOpIds(primary)
57	initPrimary(primary)
58
59	for i, m := range mixins {
60		skipped = append(skipped, mergeConsumes(primary, m)...)
61
62		skipped = append(skipped, mergeProduces(primary, m)...)
63
64		skipped = append(skipped, mergeTags(primary, m)...)
65
66		skipped = append(skipped, mergeSchemes(primary, m)...)
67
68		skipped = append(skipped, mergeSecurityDefinitions(primary, m)...)
69
70		skipped = append(skipped, mergeSecurityRequirements(primary, m)...)
71
72		skipped = append(skipped, mergeDefinitions(primary, m)...)
73
74		// merging paths requires a map of operationIDs to work with
75		skipped = append(skipped, mergePaths(primary, m, opIds, i)...)
76
77		skipped = append(skipped, mergeParameters(primary, m)...)
78
79		skipped = append(skipped, mergeResponses(primary, m)...)
80	}
81	return skipped
82}
83
84// getOpIds extracts all the paths.<path>.operationIds from the given
85// spec and returns them as the keys in a map with 'true' values.
86func getOpIds(s *spec.Swagger) map[string]bool {
87	rv := make(map[string]bool)
88	if s.Paths == nil {
89		return rv
90	}
91	for _, v := range s.Paths.Paths {
92		piops := pathItemOps(v)
93		for _, op := range piops {
94			rv[op.ID] = true
95		}
96	}
97	return rv
98}
99
100func pathItemOps(p spec.PathItem) []*spec.Operation {
101	var rv []*spec.Operation
102	rv = appendOp(rv, p.Get)
103	rv = appendOp(rv, p.Put)
104	rv = appendOp(rv, p.Post)
105	rv = appendOp(rv, p.Delete)
106	rv = appendOp(rv, p.Head)
107	rv = appendOp(rv, p.Patch)
108	return rv
109}
110
111func appendOp(ops []*spec.Operation, op *spec.Operation) []*spec.Operation {
112	if op == nil {
113		return ops
114	}
115	return append(ops, op)
116}
117
118func mergeSecurityDefinitions(primary *spec.Swagger, m *spec.Swagger) (skipped []string) {
119	for k, v := range m.SecurityDefinitions {
120		if _, exists := primary.SecurityDefinitions[k]; exists {
121			warn := fmt.Sprintf(
122				"SecurityDefinitions entry '%v' already exists in primary or higher priority mixin, skipping\n", k)
123			skipped = append(skipped, warn)
124			continue
125		}
126		primary.SecurityDefinitions[k] = v
127	}
128	return
129}
130
131func mergeSecurityRequirements(primary *spec.Swagger, m *spec.Swagger) (skipped []string) {
132	for _, v := range m.Security {
133		found := false
134		for _, vv := range primary.Security {
135			if reflect.DeepEqual(v, vv) {
136				found = true
137				break
138			}
139		}
140		if found {
141			warn := fmt.Sprintf(
142				"Security requirement: '%v' already exists in primary or higher priority mixin, skipping\n", v)
143			skipped = append(skipped, warn)
144			continue
145		}
146		primary.Security = append(primary.Security, v)
147	}
148	return
149}
150
151func mergeDefinitions(primary *spec.Swagger, m *spec.Swagger) (skipped []string) {
152	for k, v := range m.Definitions {
153		// assume name collisions represent IDENTICAL type. careful.
154		if _, exists := primary.Definitions[k]; exists {
155			warn := fmt.Sprintf(
156				"definitions entry '%v' already exists in primary or higher priority mixin, skipping\n", k)
157			skipped = append(skipped, warn)
158			continue
159		}
160		primary.Definitions[k] = v
161	}
162	return
163}
164
165func mergePaths(primary *spec.Swagger, m *spec.Swagger, opIds map[string]bool, mixIndex int) (skipped []string) {
166	if m.Paths != nil {
167		for k, v := range m.Paths.Paths {
168			if _, exists := primary.Paths.Paths[k]; exists {
169				warn := fmt.Sprintf(
170					"paths entry '%v' already exists in primary or higher priority mixin, skipping\n", k)
171				skipped = append(skipped, warn)
172				continue
173			}
174
175			// Swagger requires that operationIds be
176			// unique within a spec. If we find a
177			// collision we append "Mixin0" to the
178			// operatoinId we are adding, where 0 is mixin
179			// index.  We assume that operationIds with
180			// all the proivded specs are already unique.
181			piops := pathItemOps(v)
182			for _, piop := range piops {
183				if opIds[piop.ID] {
184					piop.ID = fmt.Sprintf("%v%v%v", piop.ID, "Mixin", mixIndex)
185				}
186				opIds[piop.ID] = true
187			}
188			primary.Paths.Paths[k] = v
189		}
190	}
191	return
192}
193
194func mergeParameters(primary *spec.Swagger, m *spec.Swagger) (skipped []string) {
195	for k, v := range m.Parameters {
196		// could try to rename on conflict but would
197		// have to fix $refs in the mixin. Complain
198		// for now
199		if _, exists := primary.Parameters[k]; exists {
200			warn := fmt.Sprintf(
201				"top level parameters entry '%v' already exists in primary or higher priority mixin, skipping\n", k)
202			skipped = append(skipped, warn)
203			continue
204		}
205		primary.Parameters[k] = v
206	}
207	return
208}
209
210func mergeResponses(primary *spec.Swagger, m *spec.Swagger) (skipped []string) {
211	for k, v := range m.Responses {
212		// could try to rename on conflict but would
213		// have to fix $refs in the mixin. Complain
214		// for now
215		if _, exists := primary.Responses[k]; exists {
216			warn := fmt.Sprintf(
217				"top level responses entry '%v' already exists in primary or higher priority mixin, skipping\n", k)
218			skipped = append(skipped, warn)
219			continue
220		}
221		primary.Responses[k] = v
222	}
223	return
224}
225
226func mergeConsumes(primary *spec.Swagger, m *spec.Swagger) (skipped []string) {
227	for _, v := range m.Consumes {
228		found := false
229		for _, vv := range primary.Consumes {
230			if v == vv {
231				found = true
232				break
233			}
234		}
235		if found {
236			// no warning here: we just skip it
237			continue
238		}
239		primary.Consumes = append(primary.Consumes, v)
240	}
241	return
242}
243
244func mergeProduces(primary *spec.Swagger, m *spec.Swagger) (skipped []string) {
245	for _, v := range m.Produces {
246		found := false
247		for _, vv := range primary.Produces {
248			if v == vv {
249				found = true
250				break
251			}
252		}
253		if found {
254			// no warning here: we just skip it
255			continue
256		}
257		primary.Produces = append(primary.Produces, v)
258	}
259	return
260}
261
262func mergeTags(primary *spec.Swagger, m *spec.Swagger) (skipped []string) {
263	for _, v := range m.Tags {
264		found := false
265		for _, vv := range primary.Tags {
266			if v.Name == vv.Name {
267				found = true
268				break
269			}
270		}
271		if found {
272			warn := fmt.Sprintf(
273				"top level tags entry with name '%v' already exists in primary or higher priority mixin, skipping\n", v.Name)
274			skipped = append(skipped, warn)
275			continue
276		}
277		primary.Tags = append(primary.Tags, v)
278	}
279	return
280}
281
282func mergeSchemes(primary *spec.Swagger, m *spec.Swagger) (skipped []string) {
283	for _, v := range m.Schemes {
284		found := false
285		for _, vv := range primary.Schemes {
286			if v == vv {
287				found = true
288				break
289			}
290		}
291		if found {
292			// no warning here: we just skip it
293			continue
294		}
295		primary.Schemes = append(primary.Schemes, v)
296	}
297	return
298}
299
300func initPrimary(primary *spec.Swagger) {
301	if primary.SecurityDefinitions == nil {
302		primary.SecurityDefinitions = make(map[string]*spec.SecurityScheme)
303	}
304	if primary.Security == nil {
305		primary.Security = make([]map[string][]string, 0, 10)
306	}
307	if primary.Produces == nil {
308		primary.Produces = make([]string, 0, 10)
309	}
310	if primary.Consumes == nil {
311		primary.Consumes = make([]string, 0, 10)
312	}
313	if primary.Tags == nil {
314		primary.Tags = make([]spec.Tag, 0, 10)
315	}
316	if primary.Schemes == nil {
317		primary.Schemes = make([]string, 0, 10)
318	}
319	if primary.Paths == nil {
320		primary.Paths = &spec.Paths{Paths: make(map[string]spec.PathItem)}
321	}
322	if primary.Paths.Paths == nil {
323		primary.Paths.Paths = make(map[string]spec.PathItem)
324	}
325	if primary.Definitions == nil {
326		primary.Definitions = make(spec.Definitions)
327	}
328	if primary.Parameters == nil {
329		primary.Parameters = make(map[string]spec.Parameter)
330	}
331	if primary.Responses == nil {
332		primary.Responses = make(map[string]spec.Response)
333	}
334}
335