Class: Angus::SDoc::DefinitionsReader

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

Constant Summary collapse

OPERATIONS = 
'operations'
CONFIGURATIONS = 
%w{service proxy_operations representations glossary messages}

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



299
300
301
 
# File 'lib/angus/definitions_reader.rb', line 299

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

.build_message(key, level, status_code, description, text) ⇒ 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:



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

def build_message(key, level, status_code, description, text)
  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
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.



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

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'])
  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.



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

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
      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
      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.



153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/angus/definitions_reader.rb', line 153

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



176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/angus/definitions_reader.rb', line 176

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
    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:



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

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.



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

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:



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

def service_definition(base_path)
  definition_hash = load_definitions(base_path)

  build_service_definition(definition_hash)
end