Class: Angus::SDoc::DefinitionsReader

Inherits:
Object
  • Object
show all
Defined in:
lib/angus/definitions_reader.rb

Constant Summary collapse

OPERATIONS = 
'operations'.freeze
CONFIGURATIONS = 
%w[service proxy_operations representations glossary messages optional].freeze

Class Method Summary collapse

Class Method Details

.build_glossary(glossary_hash) ⇒ Glossary

Builds a glossary from a hash.

Parameters:

  • glossary_hash (Hash<String, Hash>) —

    The hash contains GlossaryTerm#short_name as the key and a hash containing GlossaryTerm#long_name and GlossaryTerm#description as a value.

Returns:

  • (Glossary) —

    the glossary



330
331
332
 
# File 'lib/angus/definitions_reader.rb', line 330

def build_glossary(glossary_hash)
  Angus::SDoc::Definitions::Glossary.new(glossary_hash)
end

.build_message(key, level, status_code, description, text, fields) ⇒ Message

Builds Definitions::Message with the message data.

Parameters:

  • key (String) —

    The message key.

  • level (String) —

    The message level.

  • status_code (String) —

    The message status code.

  • description (String) —

    The message description.

  • text (String) —

    The message text.

Returns:

  • (Message) —

    the message.

Raises:



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/angus/definitions_reader.rb', line 129

def build_message(key, level, status_code, description, text, fields)
  unless level
    raise Angus::SDoc::InvalidServiceMessage.new(key ,'Can not create message without level.')
  end

  unless status_code
    raise Angus::SDoc::InvalidServiceMessage.new(key , 'Can not create message without a status code.')
  end

  message = Angus::SDoc::Definitions::Message.new
  message.key = key
  message.level = level
  message.status_code = status_code
  message.description = description
  message.text = text
  message.fields = (fields || []).map { |field| build_message_field(field['name'],
                                                                    field['description'],
                                                                    field['type'],
                                                                    field['elements_type'],
                                                                    field['required']) }

  message
end

.build_message_field(name, description, type, elements_type, required) ⇒ Message

Builds Definitions::Field with the message data.

Parameters:

  • key (String) —

    The message key.

  • level (String) —

    The message level.

  • status_code (String) —

    The message status code.

  • description (String) —

    The message description.

  • text (String) —

    The message text.

Returns:

  • (Message) —

    the message.

Raises:



166
167
168
169
170
171
172
173
174
175
 
# File 'lib/angus/definitions_reader.rb', line 166

def build_message_field(name, description, type, elements_type, required)
  field = Angus::SDoc::Definitions::MessageField.new
  field.name = name
  field.description = description
  field.type = type
  field.elements_type = elements_type
  field.required = required

  field
end

.build_messages(messages_hash) ⇒ Hash<String, Message>

Builds Definitions::Message objects for each message metadata.

Examples:

metadata message example

{'InvalidJsonError' =>
  {
    'status_code' => 422,
    'level'       => 'error',
    'description' => 'Invalid json'
  }
}

Parameters:

  • messages_hash (Hash) —

    The metadata messages.

Returns:

  • (Hash<String, Message>) —

    The hash with the messages.



105
106
107
108
109
110
111
112
113
114
 
# File 'lib/angus/definitions_reader.rb', line 105

def build_messages(messages_hash)
  messages = {}

  messages_hash.each do |key, attrs|
    messages[key] = build_message(key, attrs['level'], attrs['status_code'],
                                  attrs['description'], attrs['text'], attrs['fields'])
  end

  messages
end

.build_operations(operations_hash, messages) ⇒ Hash<String, Array<Operation>>

TODO:

Clarify the method explaining in a better way the note.

TODO:

Refactor?

Note:

It also builds and associates:

  • request elements

  • uri elements

  • messages

  • response elements

Builds Definitions::Operation objects for each operation metadata.

Parameters:

  • operations_hash (Hash) —

    The operations’ metadata.

  • messages (Array<Message>) —

    The service messages.

Returns:

  • (Hash<String, Array<Operation>>) —

    hash with namespace as key and a list of operations as values.



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
 
# File 'lib/angus/definitions_reader.rb', line 240

def build_operations(operations_hash, messages)
  result = {}

  operations_hash.each do |namespace, operations|
    operations = {} unless operations.is_a?(Hash)

    operations.each do |code_name, op_metadata|
      operation = Angus::SDoc::Definitions::Operation.new

      operation.name = op_metadata['name']
      operation.code_name = code_name
      operation.description = op_metadata['description']
      operation.path = op_metadata['path']
      operation.http_method = op_metadata['method']

      op_metadata['uri'] ||= []
      operation.uri_elements = op_metadata['uri'].map do |element_hash|
        uri_element = Angus::SDoc::Definitions::UriElement.new

        uri_element.name = element_hash['element']
        uri_element.description = element_hash['description']

        uri_element
      end

      op_metadata['request'] ||= []
      operation.request_elements = op_metadata['request'].map do |element_hash|
        request_element = Angus::SDoc::Definitions::RequestElement.new

        request_element.name = element_hash['element']
        request_element.description = element_hash['description']
        request_element.required = element_hash['required']
        request_element.type = element_hash['type']
        request_element.constraints = element_hash['constraints']
        request_element.valid_values = element_hash['valid_values']
        request_element.elements_type = element_hash['elements_type']
        request_element.optional = element_hash['optional']

        request_element
      end

      op_metadata['messages'] ||= []
      operation.messages = op_metadata['messages'].map do |message_hash|
        message_key = message_hash['key']

        message = messages[message_key]

        if message
          # The operation could override some description or level attributes, so we clone it
          message = message.clone
          message.description = message_hash['description'] if message_hash['description']
          message.level = message_hash['level'] if message_hash['level']
        else
          message = build_message(message_key, message_hash['level'], message_hash['status_code'],
                                  message_hash['description'], message_hash['text'])
        end

        message
      end

      op_metadata['response'] ||= []
      operation.response_elements = op_metadata['response'].map do |element_hash|
        response_element = Angus::SDoc::Definitions::ResponseElement.new

        response_element.name = element_hash['element']
        response_element.description = element_hash['description']
        response_element.required = element_hash['required']
        response_element.type = element_hash['type']
        response_element.default = element_hash['default']
        response_element.elements_type = element_hash['elements_type']
        response_element.optional = element_hash['optional']

        response_element
      end

      result[namespace] ||= []
      result[namespace] << operation
    end
  end

  result
end

.build_proxy_operations(proxy_operations_hash) ⇒ Object

Builds Definitions::ProxyOperation objects for each proxy operation metadata.

Parameters:

  • proxy_operations_hash (Hash) —

    The proxy operations metadata.



181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/angus/definitions_reader.rb', line 181

def build_proxy_operations(proxy_operations_hash)
  proxy_operations_hash.map do |code_name, fields|
    proxy_op = Angus::SDoc::Definitions::ProxyOperation.new
    proxy_op.code_name = code_name

    proxy_op.path = fields['path']
    proxy_op.http_method = fields['method']
    proxy_op.service_name = fields['service']

    proxy_op
  end
end

.build_representations(representations_hash) ⇒ Object

Builds Definitions::Representation objects for each representation metadata.

Parameters:

  • representations_hash (Hash) —

    The representations metadata.

  • [String] (Hash) —

    a customizable set of options



204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/angus/definitions_reader.rb', line 204

def build_representations(representations_hash)
  representations_hash.map do |name, fields|
    representation = Angus::SDoc::Definitions::Representation.new
    representation.name = name

    representation.fields = fields.map do |field_hash|
      field = Angus::SDoc::Definitions::RepresentationField.new
      field.name = field_hash['field']
      field.description = field_hash['description']
      field.type = field_hash['type']
      field.required = field_hash['required']
      field.elements_type = field_hash['elements_type']
      field.optional = field_hash['optional']
      field
    end

    representation
  end
end

.build_service_definition(definition_hash) ⇒ Angus::SDoc::Definitions::Service

It builds a Definitions::Service object from a service metadata.

Parameters:

  • definition_hash (Hash) —

    The service metadata.

Returns:



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
 
# File 'lib/angus/definitions_reader.rb', line 25

def build_service_definition(definition_hash)
  definition = Angus::SDoc::Definitions::Service.new
  definition.name = definition_hash['service']['service']
  definition.code_name = definition_hash['service']['code_name']
  definition.version = definition_hash['service']['version']

  if definition_hash['messages']
    definition.messages = build_messages(definition_hash['messages'])
  end

  if definition_hash['representations']
    definition.representations = build_representations(definition_hash['representations'])
  end

  operations_hash = definition_hash['operations'] || {}
  definition.operations = build_operations(
    operations_hash,
    definition.messages
  )

  definition.proxy_operations = build_proxy_operations(
    # As long as services uses a Angus version which don't support proxy operations,
    # we should default to an empty array.
    #
    # Remove the default when all services update Angus gem.
    definition_hash['proxy_operations'] || []
  )

  if definition_hash['glossary']
    definition.glossary = build_glossary(definition_hash['glossary'])
  end

  definition
end

.load_definitions(base_path) ⇒ Object

Reads the YML files in the given base path and returns a hash with the results loaded.



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
 
# File 'lib/angus/definitions_reader.rb', line 61

def load_definitions(base_path)
  loaded_files = []

  result = {}

  Dir["#{base_path}/{#{CONFIGURATIONS.join(',')}}.yml"].each do |config_file|
    loaded_files << config_file

    namespace = File.basename(config_file, '.*')

    result[namespace] = YAML.load_file(config_file) || {}
  end

  Dir["#{base_path}/**/#{OPERATIONS}.yml"].each do |config_file|
    unless loaded_files.include?(config_file)
      loaded_files << config_file

      namespace = File.basename(config_file, '.*')

      operation_namespace = Pathname.new(File.dirname(config_file)).basename.to_s
      operation           = YAML.load_file(config_file)

      result[namespace] ||= {}
      result[namespace][operation_namespace] = operation
    end
  end

  result
end

.service_definition(base_path) ⇒ Angus::SDoc::Definitions::Service

Returns the tree of objects for the service.

Parameters:

  • base_path (String) —

    The base path of the YML files.

Returns:



14
15
16
17
18
 
# File 'lib/angus/definitions_reader.rb', line 14

def service_definition(base_path)
  definition_hash = load_definitions(base_path)

  build_service_definition(definition_hash)
end