api_recipes 3.0.0.beta1 → 3.0.0.beta2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +152 -0
- data/lib/api_recipes/cli/import/document.rb +234 -0
- data/lib/api_recipes/cli/import/security.rb +138 -0
- data/lib/api_recipes/cli/import/server.rb +166 -0
- data/lib/api_recipes/cli/import/tree.rb +288 -0
- data/lib/api_recipes/cli/import/writer.rb +127 -0
- data/lib/api_recipes/cli/import.rb +129 -0
- data/lib/api_recipes/cli/routes.rb +50 -0
- data/lib/api_recipes/cli.rb +96 -0
- data/lib/api_recipes/version.rb +1 -1
- metadata +8 -1
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module ApiRecipes
|
|
4
|
+
module CLI
|
|
5
|
+
class Import
|
|
6
|
+
# One entry of `servers` as the options of an api: protocol, host, port,
|
|
7
|
+
# base_url and variables. Only what differs from the defaults of the gem
|
|
8
|
+
# is returned.
|
|
9
|
+
class Server
|
|
10
|
+
Result = Data.define(:options, :warnings)
|
|
11
|
+
|
|
12
|
+
# scheme, authority and path of an address; a query or a fragment is refused before.
|
|
13
|
+
ADDRESS = %r{\A(?:([^:/?#]+):)?(?://([^/?#]*))?([^?#]*)\z}
|
|
14
|
+
VARIABLE = /\{([^{}]*)\}/
|
|
15
|
+
VARIABLE_NAME = /\A[A-Za-z_]\w*\z/
|
|
16
|
+
DEFAULT_PORTS = { 'http' => 80, 'https' => 443 }.freeze
|
|
17
|
+
|
|
18
|
+
def self.read(document, index = 0)
|
|
19
|
+
new(document, index).read
|
|
20
|
+
end
|
|
21
|
+
|
|
22
|
+
def initialize(document, index)
|
|
23
|
+
@document = document
|
|
24
|
+
@index = index
|
|
25
|
+
@warnings = []
|
|
26
|
+
@names = {}
|
|
27
|
+
end
|
|
28
|
+
|
|
29
|
+
def read
|
|
30
|
+
server = chosen
|
|
31
|
+
return Result.new(options: {}, warnings: @warnings) if server.nil?
|
|
32
|
+
|
|
33
|
+
@where = "servers[#{@index}]"
|
|
34
|
+
@declared = server['variables'].is_a?(Hash) ? server['variables'] : {}
|
|
35
|
+
url = server['url']
|
|
36
|
+
raise Error, "#{@where}.url: must be a string" unless url.is_a?(String)
|
|
37
|
+
raise Error, "#{@where}.url: must not have a query or a fragment" if url.match?(/[?#]/)
|
|
38
|
+
|
|
39
|
+
scheme, authority, path = ADDRESS.match(url).captures
|
|
40
|
+
options = scheme.nil? && authority.nil? ? relative(path) : absolute(scheme, authority, path)
|
|
41
|
+
Result.new(options: options, warnings: @warnings)
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
private
|
|
45
|
+
|
|
46
|
+
def chosen
|
|
47
|
+
servers = @document.root['servers']
|
|
48
|
+
servers = [] unless servers.is_a?(Array)
|
|
49
|
+
if servers.empty?
|
|
50
|
+
raise Error, "--server #{@index}: the description names no server" unless @index.zero?
|
|
51
|
+
|
|
52
|
+
@warnings << 'the description names no server: set host in the recipe'
|
|
53
|
+
return nil
|
|
54
|
+
end
|
|
55
|
+
unless @index.between?(0, servers.size - 1)
|
|
56
|
+
raise Error, "--server #{@index}: the description has #{servers.size} servers (0 to #{servers.size - 1})"
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
server = @document.resolve(servers[@index], "servers[#{@index}]")
|
|
60
|
+
raise Error, "servers[#{@index}]: must be a mapping" unless server.is_a?(Hash)
|
|
61
|
+
|
|
62
|
+
server
|
|
63
|
+
end
|
|
64
|
+
|
|
65
|
+
def relative(path)
|
|
66
|
+
@warnings << 'the server address is relative: set host in the recipe'
|
|
67
|
+
with_variables({ base_url: base_url(path) }.compact)
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
def absolute(scheme, authority, path)
|
|
71
|
+
protocol = with_defaults(scheme.to_s, 'protocol').downcase
|
|
72
|
+
unless DEFAULT_PORTS.key?(protocol)
|
|
73
|
+
raise Error, "#{@where}.url: protocol #{Import.shown(protocol)} is not supported, only http and https"
|
|
74
|
+
end
|
|
75
|
+
raise Error, "#{@where}.url: must not contain a user or a password" if authority.to_s.include?('@')
|
|
76
|
+
|
|
77
|
+
host, port = host_and_port(authority.to_s, protocol)
|
|
78
|
+
raise Error, "#{@where}.url: has no host" if host.empty?
|
|
79
|
+
|
|
80
|
+
options = {}
|
|
81
|
+
options[:protocol] = protocol unless protocol == 'https'
|
|
82
|
+
options[:host] = renamed(host)
|
|
83
|
+
options[:port] = port if port
|
|
84
|
+
options[:base_url] = base_url(path)
|
|
85
|
+
with_variables(options.compact)
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
# The port is what follows the last colon, unless that colon belongs
|
|
89
|
+
# to an IPv6 address in brackets.
|
|
90
|
+
def host_and_port(authority, protocol)
|
|
91
|
+
match = authority.match(/\A(.*?)(?::([^:\]]*))?\z/)
|
|
92
|
+
host = match[1]
|
|
93
|
+
return [host, nil] if match[2].nil?
|
|
94
|
+
|
|
95
|
+
text = with_defaults(match[2], 'port')
|
|
96
|
+
port = text.match?(/\A\d{1,5}\z/) ? text.to_i : 0
|
|
97
|
+
raise Error, "#{@where}.url: the port must be a number from 1 to 65535" unless port.between?(1, 65_535)
|
|
98
|
+
|
|
99
|
+
[host, port == DEFAULT_PORTS[protocol] ? nil : port]
|
|
100
|
+
end
|
|
101
|
+
|
|
102
|
+
def base_url(path)
|
|
103
|
+
text = renamed(path.to_s).split('/').reject(&:empty?).join('/')
|
|
104
|
+
text.empty? ? nil : text
|
|
105
|
+
end
|
|
106
|
+
|
|
107
|
+
# The gem has no variables in the protocol and in the port: there a
|
|
108
|
+
# variable is replaced with its default.
|
|
109
|
+
def with_defaults(text, what)
|
|
110
|
+
text.gsub(VARIABLE) do
|
|
111
|
+
name = Regexp.last_match(1)
|
|
112
|
+
default = @declared[name].is_a?(Hash) ? Import.text(@declared[name]['default']) : nil
|
|
113
|
+
if default.nil?
|
|
114
|
+
raise Error, "#{@where}: the variable #{Import.shown(name)} of the #{what} has no default"
|
|
115
|
+
end
|
|
116
|
+
|
|
117
|
+
@warnings << "the variable #{Import.shown(name)} of the #{what} was replaced with its default " \
|
|
118
|
+
"#{Import.shown(default)}: the gem has no variables there"
|
|
119
|
+
default
|
|
120
|
+
end
|
|
121
|
+
end
|
|
122
|
+
|
|
123
|
+
# text with every {name} written with a name the gem accepts.
|
|
124
|
+
def renamed(text)
|
|
125
|
+
text.gsub(VARIABLE) { "{#{name_for(Regexp.last_match(1))}}" }
|
|
126
|
+
end
|
|
127
|
+
|
|
128
|
+
def name_for(original)
|
|
129
|
+
@names[original] ||= begin
|
|
130
|
+
name = original.gsub(/\W/, '_')
|
|
131
|
+
name = "_#{name}" unless VARIABLE_NAME.match?(name)
|
|
132
|
+
base = name
|
|
133
|
+
count = 1
|
|
134
|
+
name = "#{base}_#{count += 1}" while @names.value?(name)
|
|
135
|
+
unless name == original
|
|
136
|
+
@warnings << "the server variable #{Import.shown(original)} is written #{Import.shown(name)}: " \
|
|
137
|
+
'the gem accepts letters, digits and _ in a variable name'
|
|
138
|
+
end
|
|
139
|
+
name
|
|
140
|
+
end
|
|
141
|
+
end
|
|
142
|
+
|
|
143
|
+
# Adds the variables that host and base_url use, in the order they appear.
|
|
144
|
+
def with_variables(options)
|
|
145
|
+
return options if @names.empty?
|
|
146
|
+
|
|
147
|
+
options.merge(variables: @names.to_h { |original, name| [name, declaration(original)] })
|
|
148
|
+
end
|
|
149
|
+
|
|
150
|
+
def declaration(original)
|
|
151
|
+
declared = @declared[original]
|
|
152
|
+
unless declared.is_a?(Hash)
|
|
153
|
+
@warnings << "the server variable #{Import.shown(original)} is used and not defined: it has no default"
|
|
154
|
+
return {}
|
|
155
|
+
end
|
|
156
|
+
out = {}
|
|
157
|
+
default = Import.text(declared['default'])
|
|
158
|
+
out['default'] = default unless default.nil?
|
|
159
|
+
description = Import.one_line(declared['description'])
|
|
160
|
+
out['description'] = description unless description.empty?
|
|
161
|
+
out
|
|
162
|
+
end
|
|
163
|
+
end
|
|
164
|
+
end
|
|
165
|
+
end
|
|
166
|
+
end
|
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module ApiRecipes
|
|
4
|
+
module CLI
|
|
5
|
+
class Import
|
|
6
|
+
# The endpoints of a recipe, from the `paths` of a description.
|
|
7
|
+
#
|
|
8
|
+
# A segment without parameters is a name, and each name is a node. The
|
|
9
|
+
# parameters that come before a name travel with that name; those at the
|
|
10
|
+
# end of the path travel with the operation. GET on a path that ends with
|
|
11
|
+
# a name is the node itself; every other operation is a child of the node
|
|
12
|
+
# of the last name, called after its verb.
|
|
13
|
+
class Tree
|
|
14
|
+
Node = Struct.new(:name, :options, :comment, :children)
|
|
15
|
+
Result = Data.define(:nodes, :warnings, :operations, :paths, :skipped)
|
|
16
|
+
|
|
17
|
+
METHODS = %w[get put post delete options head patch trace].freeze
|
|
18
|
+
# [name on a path that ends with a name, name on a path that ends with a parameter]
|
|
19
|
+
NAMES = { 'get' => [nil, 'show'], 'post' => %w[create post], 'put' => %w[replace_all replace],
|
|
20
|
+
'patch' => %w[update_all update], 'delete' => %w[delete_all delete] }.freeze
|
|
21
|
+
PARAMETER = /\{([^{}]*)\}/
|
|
22
|
+
SUCCESS_STATUS = /\A2\d\d\z/
|
|
23
|
+
|
|
24
|
+
# A node while the tree is built. key tells apart two nodes of the same
|
|
25
|
+
# parent: it is the text of the description, so two paths that the gem
|
|
26
|
+
# writes in the same way stay two nodes. base is the name before the
|
|
27
|
+
# numbers that keep siblings apart; index finds a child node by its key.
|
|
28
|
+
Entry = Struct.new(:base, :name, :key, :path, :verb, :get, :ok_code, :comment, :operation, :children, :index)
|
|
29
|
+
|
|
30
|
+
def self.build(document, only: [], except: [])
|
|
31
|
+
new(document, only, except).build
|
|
32
|
+
end
|
|
33
|
+
|
|
34
|
+
def initialize(document, only, except)
|
|
35
|
+
@document = document
|
|
36
|
+
@only = only.map { |glob| pattern(glob) }
|
|
37
|
+
@except = except.map { |glob| pattern(glob) }
|
|
38
|
+
@warnings = []
|
|
39
|
+
@top = entry(nil, nil)
|
|
40
|
+
@operations = 0
|
|
41
|
+
@paths = 0
|
|
42
|
+
@skipped = 0
|
|
43
|
+
@servers = false
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
def build
|
|
47
|
+
paths = @document.root['paths']
|
|
48
|
+
paths.each { |path, item| add_path(path, item) } if paths.is_a?(Hash)
|
|
49
|
+
@warnings << 'servers given for a path or an operation are not used: the recipe has one address' if @servers
|
|
50
|
+
name_children(@top, nil)
|
|
51
|
+
Result.new(nodes: nodes_of(@top), warnings: @warnings, operations: @operations, paths: @paths,
|
|
52
|
+
skipped: @skipped)
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
private
|
|
56
|
+
|
|
57
|
+
def entry(base, key, **fields)
|
|
58
|
+
Entry.new(base: base, key: key, children: [], index: {}, **fields)
|
|
59
|
+
end
|
|
60
|
+
|
|
61
|
+
# ---- reading ----
|
|
62
|
+
|
|
63
|
+
def add_path(path, item)
|
|
64
|
+
unless path.is_a?(String) && path.start_with?('/')
|
|
65
|
+
@warnings << "the path #{Import.shown(path)} does not start with /: it was left out"
|
|
66
|
+
return
|
|
67
|
+
end
|
|
68
|
+
# A path that the filters leave out is not read: only counted, when
|
|
69
|
+
# its operations are in the description itself.
|
|
70
|
+
unless selected?(path)
|
|
71
|
+
@skipped += METHODS.count { |method| item[method].is_a?(Hash) } if item.is_a?(Hash)
|
|
72
|
+
return
|
|
73
|
+
end
|
|
74
|
+
item = @document.resolve(item, "paths.#{Import.shown(path)}")
|
|
75
|
+
unless item.is_a?(Hash)
|
|
76
|
+
@warnings << "the path #{Import.shown(path)} is not a mapping: it was left out"
|
|
77
|
+
return
|
|
78
|
+
end
|
|
79
|
+
methods = METHODS.select { |method| item[method].is_a?(Hash) }
|
|
80
|
+
return if methods.empty?
|
|
81
|
+
|
|
82
|
+
@paths += 1
|
|
83
|
+
@servers ||= item.key?('servers') || methods.any? { |method| item[method].key?('servers') }
|
|
84
|
+
problem = unwritable(path)
|
|
85
|
+
if problem
|
|
86
|
+
@warnings << "#{Import.shown(path)} (#{methods.size} operation#{'s' unless methods.size == 1}) cannot be " \
|
|
87
|
+
"written as a path of the gem, because #{problem}: it was left out"
|
|
88
|
+
return
|
|
89
|
+
end
|
|
90
|
+
place(path, path.split('/').reject(&:empty?), item, methods)
|
|
91
|
+
end
|
|
92
|
+
|
|
93
|
+
def selected?(path)
|
|
94
|
+
forms = [path, path.delete_prefix('/')]
|
|
95
|
+
return false if @except.any? { |regexp| forms.any? { |form| regexp.match?(form) } }
|
|
96
|
+
|
|
97
|
+
@only.empty? || @only.any? { |regexp| forms.any? { |form| regexp.match?(form) } }
|
|
98
|
+
end
|
|
99
|
+
|
|
100
|
+
# `*` crosses slashes; every other character stands for itself.
|
|
101
|
+
def pattern(glob)
|
|
102
|
+
Regexp.new("\\A#{Regexp.escape(glob.to_s).gsub('\\*', '.*')}\\z")
|
|
103
|
+
end
|
|
104
|
+
|
|
105
|
+
def parameter?(segment) = segment.match?(PARAMETER)
|
|
106
|
+
|
|
107
|
+
# Why the gem cannot write a path, or nil. The gem reads `:name` up to
|
|
108
|
+
# the last letter, digit or _; it reads `*name` at the start of a segment
|
|
109
|
+
# as a parameter that spans segments; and it joins two slashes into one.
|
|
110
|
+
def unwritable(path)
|
|
111
|
+
segments = path.split('/', -1).drop(1)
|
|
112
|
+
segments.pop if segments.last == ''
|
|
113
|
+
return 'it has an empty segment' if segments.include?('')
|
|
114
|
+
if segments.any? { |segment| segment.match?(/\{[^{}]*\}\w/) }
|
|
115
|
+
return 'text that starts with a letter, a digit or _ comes right after a parameter'
|
|
116
|
+
end
|
|
117
|
+
return 'a segment starts with * and a name' if segments.any? { |segment| segment.match?(/\A\*[A-Za-z_]/) }
|
|
118
|
+
|
|
119
|
+
nil
|
|
120
|
+
end
|
|
121
|
+
|
|
122
|
+
def place(path, segments, item, methods)
|
|
123
|
+
slash = path.length > 1 && path.end_with?('/')
|
|
124
|
+
node = @top
|
|
125
|
+
pending = []
|
|
126
|
+
segments.each_with_index do |segment, index|
|
|
127
|
+
if parameter?(segment)
|
|
128
|
+
pending << segment
|
|
129
|
+
next
|
|
130
|
+
end
|
|
131
|
+
closing = slash && index == segments.size - 1
|
|
132
|
+
key = "#{(pending + [segment]).join('/')}#{'/' if closing}"
|
|
133
|
+
node = node.index[key] ||=
|
|
134
|
+
add_child(node, entry(name_of(segment), key, path: written_path(pending + [segment], closing)))
|
|
135
|
+
pending = []
|
|
136
|
+
end
|
|
137
|
+
methods.each { |method| add_operation(node, method, pending, slash, path, item) }
|
|
138
|
+
end
|
|
139
|
+
|
|
140
|
+
def add_child(parent, child)
|
|
141
|
+
parent.children << child
|
|
142
|
+
child
|
|
143
|
+
end
|
|
144
|
+
|
|
145
|
+
def add_operation(node, method, pending, slash, path, item)
|
|
146
|
+
@operations += 1
|
|
147
|
+
operation = item[method]
|
|
148
|
+
fields = { ok_code: ok_code(operation), comment: comment(method, path, item, operation) }
|
|
149
|
+
if pending.empty? && !node.equal?(@top) && method == 'get'
|
|
150
|
+
node.get = true
|
|
151
|
+
node.ok_code = fields[:ok_code]
|
|
152
|
+
node.comment = fields[:comment]
|
|
153
|
+
return
|
|
154
|
+
end
|
|
155
|
+
|
|
156
|
+
name = if pending.empty?
|
|
157
|
+
node.equal?(@top) && method == 'get' ? 'root' : (NAMES.dig(method, 0) || method)
|
|
158
|
+
else
|
|
159
|
+
NAMES.dig(method, 1) || "#{method}_one"
|
|
160
|
+
end
|
|
161
|
+
add_child(node, entry(name, nil, operation: true, verb: method,
|
|
162
|
+
path: pending.empty? ? '' : written_path(pending, slash), **fields))
|
|
163
|
+
end
|
|
164
|
+
|
|
165
|
+
# ---- writing paths and names ----
|
|
166
|
+
|
|
167
|
+
# "/:owner/:repo/issues" for the segments ['{owner}', '{repo}', 'issues'].
|
|
168
|
+
def written_path(segments, slash)
|
|
169
|
+
used = {}
|
|
170
|
+
text = segments.map do |segment|
|
|
171
|
+
pieces = segment.split(PARAMETER, -1)
|
|
172
|
+
pieces.each_with_index.map do |piece, index|
|
|
173
|
+
index.odd? ? ":#{parameter_name(piece, used)}" : piece.gsub(':', '\\:')
|
|
174
|
+
end.join
|
|
175
|
+
end.join('/')
|
|
176
|
+
"/#{text}#{'/' if slash}"
|
|
177
|
+
end
|
|
178
|
+
|
|
179
|
+
# The name of a parameter with letters, digits and _ only, and with a
|
|
180
|
+
# number when the same path already has one with that name.
|
|
181
|
+
def parameter_name(original, used)
|
|
182
|
+
base = original.gsub(/\W/, '_')
|
|
183
|
+
base = "_#{base}" unless base.match?(/\A[A-Za-z_]/)
|
|
184
|
+
name = base
|
|
185
|
+
count = 1
|
|
186
|
+
name = "#{base}_#{count += 1}" while used.key?(name)
|
|
187
|
+
used[name] = true
|
|
188
|
+
name
|
|
189
|
+
end
|
|
190
|
+
|
|
191
|
+
def name_of(segment)
|
|
192
|
+
segment.gsub(/([a-z\d])([A-Z])/, '\1_\2').gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
|
|
193
|
+
.downcase.gsub(/[^a-z0-9]/, '_')
|
|
194
|
+
end
|
|
195
|
+
|
|
196
|
+
# The nodes born from segments take their names first, then the
|
|
197
|
+
# operations, each in the order of the description.
|
|
198
|
+
def name_children(parent, parent_name)
|
|
199
|
+
taken = {}
|
|
200
|
+
(parent.children.reject(&:operation) + parent.children.select(&:operation)).each do |child|
|
|
201
|
+
child.name = free_name(child.base, taken)
|
|
202
|
+
full = [parent_name, child.name].compact.join('.')
|
|
203
|
+
unless child.name == child.base
|
|
204
|
+
@warnings << "#{parent_name || 'the api'} has two endpoints called #{Import.shown(child.base)}: " \
|
|
205
|
+
"one is written #{Import.shown(child.name)}"
|
|
206
|
+
end
|
|
207
|
+
warn_unreachable(parent, child, full)
|
|
208
|
+
name_children(child, full)
|
|
209
|
+
end
|
|
210
|
+
end
|
|
211
|
+
|
|
212
|
+
def free_name(base, taken)
|
|
213
|
+
name = base
|
|
214
|
+
count = 1
|
|
215
|
+
name = "#{base}_#{count += 1}" while taken.key?(name)
|
|
216
|
+
taken[name] = true
|
|
217
|
+
name
|
|
218
|
+
end
|
|
219
|
+
|
|
220
|
+
def warn_unreachable(parent, child, full)
|
|
221
|
+
base = parent.equal?(@top) ? ApiRecipes::Api : ApiRecipes::Endpoint
|
|
222
|
+
method_name = Internals::Compiler::METHOD_NAME.match?(child.name)
|
|
223
|
+
return if method_name && !Internals::Handles.taken?(base, child.name.to_sym)
|
|
224
|
+
|
|
225
|
+
reason = method_name ? 'has the name of an existing method' : 'is not the name of a method'
|
|
226
|
+
@warnings << "the endpoint #{Import.shown(full)} #{reason}: reach it with [#{Import.shown(child.name)}]"
|
|
227
|
+
end
|
|
228
|
+
|
|
229
|
+
# ---- what an operation says ----
|
|
230
|
+
|
|
231
|
+
# The 2xx statuses the operation documents: one, or the list. Nothing
|
|
232
|
+
# when 200 is the only one, since the gem accepts every 2xx by default.
|
|
233
|
+
def ok_code(operation)
|
|
234
|
+
responses = operation['responses']
|
|
235
|
+
return nil unless responses.is_a?(Hash)
|
|
236
|
+
|
|
237
|
+
codes = responses.keys.map { |key| Import.text(key).to_s }.grep(SUCCESS_STATUS).map(&:to_i).uniq.sort
|
|
238
|
+
return nil if codes.empty? || codes == [200]
|
|
239
|
+
|
|
240
|
+
codes.size == 1 ? codes.first : codes
|
|
241
|
+
end
|
|
242
|
+
|
|
243
|
+
def comment(method, path, item, operation)
|
|
244
|
+
details = []
|
|
245
|
+
details << operation['operationId'] if operation['operationId'].is_a?(String)
|
|
246
|
+
details << 'deprecated' if operation['deprecated'] == true
|
|
247
|
+
query = query_parameters(path, item, operation)
|
|
248
|
+
details << "query: #{query.join(', ')}" unless query.empty?
|
|
249
|
+
Import.one_line("#{method.upcase} #{path}#{" (#{details.join('; ')})" unless details.empty?}")
|
|
250
|
+
end
|
|
251
|
+
|
|
252
|
+
# The query parameters of the path and of the operation, the second
|
|
253
|
+
# over the first, with a star on the required ones.
|
|
254
|
+
def query_parameters(path, item, operation)
|
|
255
|
+
found = {}
|
|
256
|
+
[item['parameters'], operation['parameters']].each do |list|
|
|
257
|
+
next unless list.is_a?(Array)
|
|
258
|
+
|
|
259
|
+
list.each do |parameter|
|
|
260
|
+
parameter = @document.resolve(parameter, "paths.#{Import.shown(path)}.parameters")
|
|
261
|
+
next unless parameter.is_a?(Hash) && parameter['in'] == 'query' && parameter['name'].is_a?(String)
|
|
262
|
+
|
|
263
|
+
found[parameter['name']] = parameter['required'] == true
|
|
264
|
+
end
|
|
265
|
+
end
|
|
266
|
+
found.map { |name, required| "#{name}#{'*' if required}" }
|
|
267
|
+
end
|
|
268
|
+
|
|
269
|
+
# ---- result ----
|
|
270
|
+
|
|
271
|
+
def nodes_of(parent)
|
|
272
|
+
parent.children.map do |child|
|
|
273
|
+
Node.new(child.name, options_of(child), child.comment, nodes_of(child))
|
|
274
|
+
end
|
|
275
|
+
end
|
|
276
|
+
|
|
277
|
+
def options_of(child)
|
|
278
|
+
options = {}
|
|
279
|
+
options[:path] = child.path unless child.path == "/#{child.name}"
|
|
280
|
+
options[:verb] = child.verb if child.verb && child.verb != 'get'
|
|
281
|
+
options[:route] = false unless child.operation || child.get
|
|
282
|
+
options[:ok_code] = child.ok_code if child.ok_code
|
|
283
|
+
options
|
|
284
|
+
end
|
|
285
|
+
end
|
|
286
|
+
end
|
|
287
|
+
end
|
|
288
|
+
end
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'yaml'
|
|
4
|
+
|
|
5
|
+
module ApiRecipes
|
|
6
|
+
module CLI
|
|
7
|
+
class Import
|
|
8
|
+
# The text of a recipe: the api, its options, the tree of endpoints and a
|
|
9
|
+
# comment beside each operation. Every name and every value is written by
|
|
10
|
+
# Ruby's YAML generator. Before the text is returned it is read back and
|
|
11
|
+
# compared with the data it was written from.
|
|
12
|
+
class Writer
|
|
13
|
+
API_KEYS = %i[protocol host port base_url auth variables].freeze
|
|
14
|
+
ENDPOINT_KEYS = %i[path verb route ok_code].freeze
|
|
15
|
+
COMMENT_COLUMN = 34
|
|
16
|
+
MAX_NAME = 1000
|
|
17
|
+
# Control characters, and the two separators that YAML reads as a new line.
|
|
18
|
+
LINE_BREAKING = /[[:cntrl:]\u2028\u2029]/
|
|
19
|
+
INTERNAL = 'internal error: the recipe does not read back as it was written, so nothing was written'
|
|
20
|
+
|
|
21
|
+
def initialize(name:, options:, nodes:, header: nil)
|
|
22
|
+
@name = name
|
|
23
|
+
@options = options
|
|
24
|
+
@nodes = nodes
|
|
25
|
+
@header = header
|
|
26
|
+
end
|
|
27
|
+
|
|
28
|
+
def to_yaml
|
|
29
|
+
@lines = []
|
|
30
|
+
header = Import.one_line(@header)
|
|
31
|
+
@lines << "# #{header}" unless header.empty?
|
|
32
|
+
data = { @name => api }
|
|
33
|
+
text = "#{@lines.join("\n")}\n"
|
|
34
|
+
raise Error, INTERNAL unless read_back(text) == data
|
|
35
|
+
|
|
36
|
+
text
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
private
|
|
40
|
+
|
|
41
|
+
def read_back(text)
|
|
42
|
+
YAML.safe_load(text)
|
|
43
|
+
rescue Psych::Exception
|
|
44
|
+
raise Error, INTERNAL
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
def api
|
|
48
|
+
line(0, "#{scalar(@name, '', 'the name of the api')}:")
|
|
49
|
+
body = {}
|
|
50
|
+
API_KEYS.each do |key|
|
|
51
|
+
body[key.to_s] = value(1, key.to_s, @options[key], "#{@name}.#{key}") if @options.key?(key)
|
|
52
|
+
end
|
|
53
|
+
unless @nodes.empty?
|
|
54
|
+
line(1, 'endpoints:')
|
|
55
|
+
body['endpoints'] = nodes(@nodes, 2, "#{@name}.endpoints")
|
|
56
|
+
end
|
|
57
|
+
body.empty? ? nil : body
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
def nodes(list, indent, where)
|
|
61
|
+
list.to_h do |node|
|
|
62
|
+
name = scalar(node.name, where, 'the name of an endpoint')
|
|
63
|
+
comment = Import.one_line(node.comment)
|
|
64
|
+
line(indent, "#{name}:", comment.empty? ? nil : comment)
|
|
65
|
+
here = "#{where}.#{node.name}"
|
|
66
|
+
body = {}
|
|
67
|
+
ENDPOINT_KEYS.each do |key|
|
|
68
|
+
body[key.to_s] = value(indent + 1, key.to_s, node.options[key], "#{here}.#{key}") if node.options.key?(key)
|
|
69
|
+
end
|
|
70
|
+
unless node.children.empty?
|
|
71
|
+
line(indent + 1, 'endpoints:')
|
|
72
|
+
body['endpoints'] = nodes(node.children, indent + 2, "#{here}.endpoints")
|
|
73
|
+
end
|
|
74
|
+
[node.name, body.empty? ? nil : body]
|
|
75
|
+
end
|
|
76
|
+
end
|
|
77
|
+
|
|
78
|
+
# Writes key and content, and returns the content as YAML will read it.
|
|
79
|
+
def value(indent, key, content, where)
|
|
80
|
+
key = scalar(key, where, 'a name')
|
|
81
|
+
case content
|
|
82
|
+
when Hash
|
|
83
|
+
if content.empty?
|
|
84
|
+
line(indent, "#{key}: {}")
|
|
85
|
+
{}
|
|
86
|
+
else
|
|
87
|
+
line(indent, "#{key}:")
|
|
88
|
+
content.to_h { |name, item| [name.to_s, value(indent + 1, name.to_s, item, "#{where}.#{name}")] }
|
|
89
|
+
end
|
|
90
|
+
when Array
|
|
91
|
+
line(indent, "#{key}: [#{content.map { |item| scalar(item, where) }.join(', ')}]")
|
|
92
|
+
content
|
|
93
|
+
else
|
|
94
|
+
line(indent, "#{key}: #{scalar(content, where)}")
|
|
95
|
+
content
|
|
96
|
+
end
|
|
97
|
+
end
|
|
98
|
+
|
|
99
|
+
def line(indent, text, comment = nil)
|
|
100
|
+
text = "#{' ' * indent}#{text}"
|
|
101
|
+
text = "#{text.ljust(COMMENT_COLUMN - 1)} # #{comment}" if comment
|
|
102
|
+
@lines << text
|
|
103
|
+
end
|
|
104
|
+
|
|
105
|
+
# One name or one plain value as the YAML generator writes it, on one
|
|
106
|
+
# line. Text that a recipe file would run as ERB, or that would start a
|
|
107
|
+
# new line, is refused; the message says where and never shows it.
|
|
108
|
+
def scalar(content, where, what = nil)
|
|
109
|
+
place = [where.empty? ? nil : "#{where}:", what].compact.join(' ')
|
|
110
|
+
if content.is_a?(String)
|
|
111
|
+
raise Error, "#{place} is not valid text" unless content.valid_encoding?
|
|
112
|
+
raise Error, "#{place} contains <%, which a recipe file would run as ERB" if content.include?('<%')
|
|
113
|
+
raise Error, "#{place} contains a control character" if content.match?(LINE_BREAKING)
|
|
114
|
+
# YAML does not read a name longer than 1024 characters.
|
|
115
|
+
raise Error, "#{place} is longer than #{MAX_NAME} characters" if what && content.length > MAX_NAME
|
|
116
|
+
elsif !(content.is_a?(Integer) || content == true || content == false)
|
|
117
|
+
raise Error, INTERNAL
|
|
118
|
+
end
|
|
119
|
+
written = YAML.dump([content], line_width: -1)[/\A---\n- (.*)\n\z/m, 1]
|
|
120
|
+
raise Error, INTERNAL if written.nil? || written.include?("\n")
|
|
121
|
+
|
|
122
|
+
written
|
|
123
|
+
end
|
|
124
|
+
end
|
|
125
|
+
end
|
|
126
|
+
end
|
|
127
|
+
end
|