sp-duh 2.0.6

data/lib/sp/duh/jsonapi/doc/apidoc_documentation_format_generator.rb

@@ -0,0 +1,286 @@
+module SP
+  module Duh
+    module JSONAPI
+      module Doc
+
+        class ApidocDocumentationFormatGenerator
+
+          def generate(resource_parser, version, doc_folder_path)
+            @version = version
+            # First create an index of all resources (for relationships linking)
+            @resources = {}
+            resource_parser.each do |resource|
+              next if get_resource_data(resource, :scope) != :public
+              @resources[get_resource_name(resource)] = get_resource_link(resource)
+            end
+            _log "Generating Apidoc documentation for version #{version} in folder #{doc_folder_path}", "JSONAPI::Doc::Generator"
+            resource_parser.each do |resource|
+              next if get_resource_data(resource, :scope) != :public
+              generate_documentation(resource, doc_folder_path)
+            end
+          end
+
+          private
+
+            def generate_documentation(resource, folder_path)
+              readonly = (get_resource_data(resource, :readonly) == true)
+              _log "   Generating documentation for resource #{resource}", "JSONAPI::Doc::Generator"
+              File.open(File.join(folder_path, "#{get_resource_name(resource)}.js"), File::CREAT | File::TRUNC | File::RDWR) do |f|
+                wrap_in_comments(f) { append_lines(f, get_post_documentation(resource)) } if !readonly
+                wrap_in_comments(f) { append_lines(f, get_get_documentation(resource)) }
+                wrap_in_comments(f) { append_lines(f, get_patch_documentation(resource)) } if !readonly
+                wrap_in_comments(f) { append_lines(f, get_delete_documentation(resource)) } if !readonly
+                wrap_in_comments(f) { append_lines(f, get_get_documentation(resource, false)) }
+              end
+            end
+
+            def get_resource_link(resource)
+              group = get_resource_data(resource, :group).gsub(' ', '_')
+              get_action_name = "#{('Get_' + get_resource_name(resource)).camelcase}"
+              link = '#api-' + "#{group}-#{get_action_name}"
+              link
+            end
+
+            def wrap_in_comments(f) ; write_header(f) ; yield ; write_footer(f) ; end
+
+            def get_get_documentation(resource, single = true)
+              documentation = get_api_method_header(resource, :get, single) + get_api_method_params(resource, :get, single) + get_attribute_list(resource, single) + get_api_method_success_example(resource, :get, single)
+              documentation.compact!
+              documentation
+            end
+
+            def get_post_documentation(resource)
+              documentation = get_api_method_header(resource, :post) + get_api_method_params(resource, :post) + get_attribute_list(resource) + get_api_method_success_example(resource, :post)
+              documentation.compact!
+              documentation
+            end
+
+            def get_patch_documentation(resource)
+              documentation = get_api_method_header(resource, :patch) + get_api_method_params(resource, :patch) + get_attribute_list(resource) + get_api_method_success_example(resource, :patch)
+              documentation.compact!
+              documentation
+            end
+
+            def get_delete_documentation(resource)
+              documentation = get_api_method_header(resource, :delete) + get_api_method_params(resource, :delete) + get_api_method_success_example(resource, :delete)
+              documentation.compact!
+              documentation
+            end
+
+            def get_api_method_header(resource, method, single = true)
+              data = []
+              resource_name = get_resource_name(resource)
+              resource_description = get_resource_data(resource, :description)
+              resource_description = [ resource_name.titlecase ] if resource_description.blank?
+              method_title = "#{get_human_method(method).capitalize} #{uncapitalize(resource_description.first)} #{(single ? '' : 'list')}"
+              case
+                when method.to_sym.in?([ :patch, :delete ]) || (method.to_sym == :get && single)
+                  url = "/#{resource_name}/:id"
+                else
+                  url = "/#{resource_name}"
+              end
+              data << "@api {#{method}} #{url} #{method_title}"
+              data << "@apiVersion #{@version}"
+              data << "@apiName #{(method.to_s + '_' + resource_name + (single ? '' : '_list')).camelcase}"
+              data << "@apiGroup #{get_resource_data(resource, :group)}"
+              data << "@apiDescription #{method_title}"
+              resource_description.each_with_index do |d, i|
+                next if i == 0
+                data << d
+              end
+              data
+            end
+
+            def get_attribute_type_name_and_description(a)
+              data = ""
+              type = nil
+              if !a[:catalog].nil?
+                type = get_type(a[:catalog])
+                data += "{#{type}} "
+              end
+              description = (a[:description] || []).join('. ')
+              if a[:association]
+                if type && @resources[type.gsub('[]','')]
+                  description = '<a href="' + @resources[type.gsub('[]','')] + '">' + description + '</a>'
+                end
+              end
+              data += "#{a[:name]} #{description}"
+              data
+            end
+
+            def get_api_method_params(resource, method, single = true)
+              a = get_resource_data(resource, :id)
+              id_param = (a.nil? ? -1 : a.to_i)
+              params = []
+              case
+                when method.to_sym.in?([ :post, :patch, :delete ]) || (method.to_sym == :get && single)
+                  if resource[:attributes]
+                    resource[:attributes].each_with_index do |a, i|
+                      next if a[:readonly] == true
+                      next if i == id_param && method.to_sym == :post
+                      data = "@apiParam "
+                      params << "@apiParam " + get_attribute_type_name_and_description(a)
+                      break if i == id_param && method.to_sym.in?([ :get, :delete ])
+                    end
+                  end
+              end
+              params = params + get_api_method_param_example(resource, method) if method.to_sym.in?([ :post, :patch ])
+              params
+            end
+
+            def get_attribute_list(resource, single = true)
+              if resource[:attributes]
+                resource[:attributes].map do |a|
+                  "@apiSuccess " + get_attribute_type_name_and_description(a)
+                end
+              else
+                []
+              end
+            end
+
+            def get_api_method_param_example(resource, method)
+              data = [ "@apiParamExample {json} Request body example", "" ]
+              data = data + get_api_method_json(resource, method)
+              data
+            end
+
+            def get_api_method_success_example(resource, method, single = true)
+              data = [ "@apiSuccessExample {json} Success response example", "HTTP/1.1 200 OK", "" ]
+              case
+                when method.to_sym.in?([ :get, :patch, :post ])
+                  data = data + get_api_method_json(resource, :get, single)
+              end
+              data
+            end
+
+            def uncapitalize(text)
+              words = text.split(' ')
+              words[0] = words[0].downcase
+              words.join(' ')
+            end
+
+            def get_human_method(m) ; m.to_sym == :post ? :create : (m.to_sym == :patch ? :update : m.to_sym) ; end
+            def get_resource_name(r) ; get_resource_data(r, :name) ; end
+            def get_resource_data(r, name) ; r[:resource][name] ; end
+            def get_attribute(r, i) ; r[:attributes][i] if r[:attributes] ; end
+            def get_attribute_data(r, i, name) ; get_attribute(r, i)[name] ; end
+            def get_type(r) ; r['format_type'].gsub(/character varying\(\d+\)/, 'text').gsub(/character/, 'text').gsub(' without time zone', '').gsub(' with time zone', '') ; end
+
+            def get_api_method_json(resource, method, single = true)
+              json = [ '{' ]
+              case
+                when method.to_sym.in?([ :post, :patch ]) || (method.to_sym == :get && single)
+                  json << '  "data": {'
+                  json = json + get_resource_json(resource, method.to_sym != :post, !method.to_sym.in?([ :post, :patch ]))
+                  json << '  }'
+                when method.to_sym == :get && !single
+                  json << '  "data": [{'
+                  json = json + get_resource_json(resource)
+                  json << '  }]'
+              end
+              json << '}'
+              json
+            end
+
+            def get_resource_json(resource, include_id = true, include_readonly = true)
+              json = []
+              json << '    "type": "' + get_resource_name(resource) + '",'
+              id_index = get_resource_data(resource, :id).to_i
+              json << '    "id": "' + get_default_value_for_attribute(resource, id_index) + '",' if include_id
+              json << '    "attributes": {'
+              resource[:attributes].each_with_index do |a, i|
+                next if i == id_index
+                next if a[:readonly] == true && !include_readonly
+                next if a[:association]
+                json << '      "' + a[:name].to_s + '": ' + get_default_value_for_attribute(resource, i) + ','
+              end
+              delete_comma(json)
+              json << '    }'
+              has_associations = false
+              resource[:attributes].each_with_index do |a, i|
+                next if !a[:association]
+                next if a[:readonly] == true && !include_readonly
+                if !has_associations
+                  add_comma(json)
+                  json << '    "relationships": {'
+                  has_associations = true
+                end
+                json = json + get_association_json(resource, i, a)
+              end
+              if has_associations
+                delete_comma(json)
+                json << '    }'
+              end
+              json
+            end
+
+            def add_comma(lines) ; lines[lines.length-1] = lines[lines.length-1] + ',' ; end
+            def delete_comma(lines) ; lines[lines.length-1] = lines[lines.length-1][0..lines[lines.length-1].length-2] ; end
+
+            def get_association_json(resource, i, attribute)
+              json = []
+              json << '      "' + attribute[:name] + '": {'
+              if attribute[:association] == :'to-many'
+                json << '        "data": ['
+                json << '          {'
+                json << '            "type": "' + get_type(attribute[:catalog]).sub('[]', '') + '",'
+                json << '            "id": ' + get_default_value_for_attribute(resource, i)
+                json << '          },'
+                json << '          {'
+                json << '            "type": "' + get_type(attribute[:catalog]).sub('[]', '') + '",'
+                json << '            "id": ' + (get_default_value_for_attribute(resource, i).to_i + 1).to_s
+                json << '          }'
+                json << '        ],'
+              else
+                json << '        "data": {'
+                json << '          "type": "' + get_type(attribute[:catalog]) + '",'
+                json << '          "id": ' + get_default_value_for_attribute(resource, i)
+                json << '        },'
+              end
+              delete_comma(json)
+              json << '      },'
+              json
+            end
+
+            def get_default_value_for_attribute(r, i)
+              a = get_attribute(r, i)
+              if a.nil?
+                'null'
+              else
+                if a[:name].to_sym == :id || a[:association]
+                  return "1"
+                else
+                  default = a[:example]
+                  if !default.nil? && !a[:catalog].nil?
+                    default = default.gsub('"','').gsub("'", '')
+                    type = get_type(a[:catalog])
+                    case type
+                    when 'boolean'
+                      default = default
+                    when 'integer', 'bigint'
+                      default = default
+                    when 'numeric', 'decimal', 'float'
+                      default = default
+                    else
+                      default = '"' + default + '"'
+                    end
+                  end
+                  if default.nil?
+                    default = 'null'
+                  end
+                  default
+                end
+              end
+            end
+
+            def write_header(f) ; f.puts '/**' ; end
+            def append_lines(f, lines) ; lines.each { |l| append_line(f, l) } ; end
+            def append_line(f, line = nil) ; f.puts ' * ' + line.to_s ; end
+            def write_footer(f) ; f.puts '*/' ; end
+
+        end
+
+      end
+    end
+  end
+end

data/lib/sp/duh/jsonapi/doc/generator.rb

@@ -0,0 +1,32 @@
+require 'sp/duh/jsonapi/doc/victor_pinus_metadata_format_parser'
+require 'sp/duh/jsonapi/doc/apidoc_documentation_format_generator'
+
+module SP
+  module Duh
+    module JSONAPI
+      module Doc
+
+        class Generator
+
+          def initialize(pg_connection)
+            @pg_connection = pg_connection
+          end
+
+          def generate(resource_publisher, version, doc_folder_path = File.join(Dir.pwd, 'apidoc'))
+            # Load the JSONAPI resources from the given publishers
+            @parser = SP::Duh::JSONAPI::Doc::VictorPinusMetadataFormatParser.new(@pg_connection)
+            @parser.parse(resource_publisher)
+            # Generate the resources documentation
+            @generator = SP::Duh::JSONAPI::Doc::ApidocDocumentationFormatGenerator.new
+            @generator.generate(@parser, version, doc_folder_path)
+            # Regenerate the documentation site
+            _log "Generating the documentation site in #{doc_folder_path}", "JSONAPI::Doc::Generator"
+            `(cd #{doc_folder_path} && apidoc)`
+          end
+
+        end
+
+      end
+    end
+  end
+end

data/lib/sp/duh/jsonapi/doc/schema_catalog_helper.rb

@@ -0,0 +1,97 @@
+module SP
+  module Duh
+    module JSONAPI
+      module Doc
+
+        class SchemaCatalogHelper
+
+          def initialize(pg_connection)
+            @pg_connection = pg_connection
+            @default_schema = get_db_first_sharded_schema()
+            clear_settings
+          end
+
+          def clear_settings ; @settings = {} ; @attrs = nil ; end
+          def add_setting(setting, value) ; @settings[setting.to_sym] = value ; end
+          def get_settings
+            @settings.merge({
+              schema: (@settings[:use_schema] ? @default_schema : 'public')
+            })
+          end
+
+          def get_attribute(name)
+            if @attrs.nil?
+              if get_settings[:table_name].nil?
+                @attrs = get_db_function_attribute_definitions(get_settings[:schema], get_settings[:function_name])
+              else
+                @attrs = get_db_table_attribute_definitions(get_settings[:schema], get_settings[:table_name])
+              end
+            end
+            @attrs[name.to_s]
+          end
+
+          private
+
+            def get_db_first_sharded_schema
+              result = @pg_connection.exec %q[
+                SELECT
+                  c.schema_name
+                FROM
+                  public.companies c
+                WHERE
+                  c.use_sharded_company = true
+                LIMIT 1
+              ]
+              result[0]['schema_name']
+            end
+
+            def get_db_table_attribute_definitions(schema, table_name)
+              return {} if schema.nil? || table_name.nil?
+              result = @pg_connection.exec %Q[
+                SELECT
+                  t.tablename::TEXT AS object_name,
+                  a.attname,
+                  pg_catalog.format_type(a.atttypid, a.atttypmod),
+                  (SELECT substring(pg_catalog.pg_get_expr(d.adbin, d.adrelid) for 128) FROM pg_catalog.pg_attrdef d WHERE d.adrelid = a.attrelid AND d.adnum = a.attnum AND a.atthasdef) AS default_value,
+                  a.attnotnull
+                FROM pg_catalog.pg_attribute a
+                  JOIN pg_catalog.pg_class c ON a.attrelid = c.oid
+                  JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+                  JOIN pg_catalog.pg_tables t ON c.oid = (t.schemaname || '.' || t.tablename)::regclass::oid
+                WHERE a.attnum > 0
+                  AND NOT a.attisdropped
+                  AND n.nspname = '#{schema}'
+                  AND t.tablename = '#{table_name}'
+              ]
+              definitions = {}
+              result.each { |a| definitions.merge!({ a['attname'] => a })  }
+              definitions
+            end
+
+            def get_db_function_attribute_definitions(schema, function_name)
+              return {} if schema.nil? || function_name.nil?
+              result = @pg_connection.exec %Q[
+                SELECT
+                  trim(split_part(regexp_replace(p.argument, E'^OUT ', ''), ' ', 1)) AS attname,
+                  trim(split_part(regexp_replace(p.argument, E'^OUT ', ''), ' ', 2)) AS format_type
+                FROM (
+                  SELECT
+                    trim(unnest(regexp_split_to_array(pg_catalog.pg_get_function_arguments(p.oid), E','))) as argument
+                  FROM pg_catalog.pg_proc p
+                       LEFT JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+                  WHERE p.proname ~ '^(#{function_name})$'
+                    AND n.nspname ~ '^(#{schema})$'
+                ) p
+                WHERE
+                  CASE WHEN p.argument ~ '^OUT' THEN true ELSE false END = true
+              ]
+              definitions = {}
+              result.each { |a| definitions.merge!({ a['attname'] => a })  }
+              definitions
+            end
+        end
+
+      end
+    end
+  end
+end

data/lib/sp/duh/jsonapi/doc/victor_pinus_metadata_format_parser.rb

@@ -0,0 +1,374 @@
+require 'sp/duh/jsonapi/doc/schema_catalog_helper'
+
+module SP
+  module Duh
+    module JSONAPI
+      module Doc
+
+        class VictorPinusMetadataFormatParser
+          include Enumerable
+
+          def resources ; @resources || [] ; end
+          def resource_names ; resources.map { |r| r.keys.first } ; end
+
+          def initialize(pg_connection)
+            @pg_connection = pg_connection
+            @schema_helper = SchemaCatalogHelper.new(pg_connection)
+          end
+
+          def parse(publisher, public_only = true)
+            @public_only = public_only
+            begin
+              publisher = publisher.constantize if publisher.is_a?(String)
+              raise Exceptions::InvalidResourcePublisherError.new(publisher: publisher.name) if !publisher.include?(ResourcePublisher)
+              @publisher = publisher
+            rescue StandardError => e
+              raise Exceptions::InvalidResourcePublisherError.new(publisher: publisher.is_a?(String) ? publisher : publisher.name)
+            end
+            @resources = []
+            add_resources_from_folder(publisher.jsonapi_resources_root)
+            @resources
+          end
+
+          def each(&block)
+            @resources.each do |resource|
+              parsed_resource = parse_resource(resource)
+              block.call(parsed_resource) if !parsed_resource.nil?
+            end
+          end
+
+          private
+
+            def add_resources_from_folder(folder_name)
+              @resources ||= []
+              # First load resources at the root folder
+              Dir.glob(File.join(folder_name, '*.yml')) do |configuration_file|
+                add_resources_from_file(configuration_file)
+              end
+              # Then load resources at the inner folders
+              Dir.glob(File.join(folder_name, '*', '*.yml')) do |configuration_file|
+                add_resources_from_file(configuration_file)
+              end
+              @resources
+            end
+
+            def add_resources_from_file(configuration_file)
+              _log "Loading resources from file #{configuration_file}", "JSONAPI::Doc::Parser"
+              configuration =  YAML.load_file(configuration_file)
+              if configuration.is_a? Hash
+                add_resource(configuration, configuration_file)
+              else
+                if configuration.is_a? Array
+                  configuration.each { |resource| add_resource(resource, configuration_file) }
+                else
+                  raise Exceptions::InvalidResourceConfigurationError.new(file: configuration_file)
+                end
+              end
+            end
+
+            def add_resource(resource, configuration_file)
+              raise Exceptions::InvalidResourceConfigurationError.new(file: configuration_file) if (resource.keys.count != 1)
+              resource_name = resource.keys[0]
+              _log "   Loading resource #{resource_name}", "JSONAPI::Doc::Parser"
+              processed = false
+              @resources.each_with_index do |r, i|
+                if r.keys.include?(resource_name)
+                  @resources[i] = get_resource_index(resource_name, configuration_file)
+                  processed = true
+                  break
+                end
+              end
+              @resources << get_resource_index(resource_name, configuration_file) if !processed
+            end
+
+            def get_resource_index(resource_name, configuration_file)
+              {
+                resource_name.to_sym => {
+                  group: @publisher.name,
+                  file: configuration_file
+                }
+              }
+            end
+
+            def parse_resource(resource)
+              resource_name = resource.keys[0].to_s
+              resource_file = resource.values[0][:file]
+              _log "   Processing resource #{resource_name} in file #{resource_file}", "JSONAPI::Doc::Parser"
+              metadata = parse_file(resource_name, resource_file)
+              if !metadata.nil?
+                metadata[:resource] = {} if !metadata.has_key?(:resource)
+                metadata[:resource] = metadata[:resource].merge({
+                  name: resource_name
+                })
+                if metadata[:resource][:group].blank?
+                  # group = /^(?<group>\w+?)_/.match(resource_name)
+                  # resource_group = (group ? group[:group].capitalize : resource.values[0][:group])
+                  resource_group = resource_name.capitalize
+                  metadata[:resource][:group] = resource_group
+                end
+              else
+                _log "   Ignoring PRIVATE resource #{resource_name} in file #{resource_file}", "JSONAPI::Doc::Parser"
+              end
+              metadata
+            end
+
+            def parse_file(resource, resource_file)
+
+              context = nil
+              metadata = {}
+              indent = nil
+
+              lines = File.readlines(resource_file)
+
+              table_name = function_name = data_schema = use_schema = nil
+              lines.each_with_index do |line, i|
+
+                # Ignore empty lines
+                next if line.strip.blank?
+
+                # Process resource definition beginning
+
+                r = get_resource(line, indent)
+                # First get the starting line of the resource...
+                next if !metadata.has_key?(:resource) && (r.first.nil? || r.first.strip != resource)
+                # ... but exit if we reached another resource
+                break if metadata.has_key?(:resource) && !r.first.nil? && r.first.strip != resource
+                if !r.first.nil? && !metadata.has_key?(:resource)
+                  context = :resource
+                  indent = r.last.length
+                  # Get the resource metadata:
+                  m, example, tags = get_metadata_for(lines, i, r)
+                  scope = :private
+                  scope = :public if 'public'.in?(tags)
+                  metadata[:resource] = {
+                    description: m,
+                    scope: scope
+                  }
+                  tags.each do |t|
+                    case
+                    when t.start_with?('group')
+                      v = t.split('=')
+                      metadata[:resource][:group] = v.last.strip
+                    when t == 'readonly'
+                      metadata[:resource][:readonly] = true
+                    end
+                  end
+                end
+
+                # Return now if resource is private
+                return nil if scope == :private && @public_only
+
+                if context == :resource
+
+                  # Process data structure
+                  table_name = get_value_of('pg-table', line) if table_name.nil?
+                  function_name = get_value_of('pg-function', line) if function_name.nil?
+                  data_schema = get_value_of('pg-schema', line) if data_schema.nil?
+
+                  use_schema = get_value_of('request-schema', line) if use_schema.nil?
+                  use_schema = get_value_of('request-sharded-schema', line) if use_schema.nil?
+
+                  # Process resource attributes
+
+                  if is_beginning_of_attribute_section?(line)
+                    context = :attributes
+                    metadata[:resource] = {} if !metadata.has_key?(:resource)
+                    @schema_helper.clear_settings
+                    @schema_helper.add_setting(:schema, data_schema) if !data_schema.nil?
+                    @schema_helper.add_setting(:table_name, table_name) if !table_name.nil?
+                    @schema_helper.add_setting(:function_name, function_name) if !function_name.nil?
+                    @schema_helper.add_setting(:use_schema, use_schema) if !use_schema.nil?
+
+                    metadata[:resource][:catalog] = {
+                      sharded_schema: use_schema == 'true'
+                    }
+                    metadata[:resource][:catalog][:schema] = data_schema if !data_schema.nil?
+                    metadata[:resource][:catalog][:table_name] = table_name if !table_name.nil?
+                    metadata[:resource][:catalog][:function_name] = function_name if !function_name.nil?
+                    metadata[:attributes] = []
+                    next
+                  end
+
+                end
+
+                readonly = false
+
+                if context == :attributes
+
+                  readonly = false
+                  a = get_attribute(line)
+                  if !a.first.nil?
+                    metadata[:resource][:id] = metadata[:attributes].length if a.first.strip.to_sym == :id
+                    # Get the attribute metadata
+                    description, example, tags = get_metadata_for(lines, i, a)
+                    readonly = true if 'readonly'.in?(tags)
+                    metadata[:attributes] << {
+                      name: a.first.strip,
+                      catalog: @schema_helper.get_attribute(a.first),
+                      description: description,
+                      example: example,
+                      readonly: readonly
+                    }
+                  else
+                    a = get_jsonapi_attribute(line)
+                    if !a.first.nil?
+                      case
+                      when a.first.in?([ 'to-one', 'to-many' ])
+                        context = a.first.to_sym
+                        readonly = false
+                        next
+                      end
+                    else
+                      column = get_value_of('pg-column', line)
+                      metadata[:attributes].last.merge!({
+                        catalog: @schema_helper.get_attribute(column)
+                      }) if column
+                    end
+                  end
+
+                end
+
+                if context == :"to-one" || context == :"to-many"
+                  a = get_jsonapi_attribute(line)
+                  if a.first.nil?
+                    type = get_value_of('resource', line)
+                    table_name = get_value_of('pg-table', line)
+                    if !type.nil? || !table_name.nil?
+                      type ||= table_name
+                      metadata[:attributes].last.merge!({
+                        catalog: {
+                          'format_type' => (context == :'to-one' ? type : "#{type}[]")
+                        }
+                      })
+                    end
+                  else
+                    case
+                    when a.first.in?([ 'to-one', 'to-many' ])
+                      context = a.first.to_sym
+                      next
+                    else
+                      description, example, tags = get_metadata_for(lines, i, a)
+                      readonly = true if 'readonly'.in?(tags)
+                      metadata[:attributes] << {
+                        name: a.first.strip,
+                        association: context,
+                        description: description,
+                        example: example,
+                        readonly: readonly
+                      }
+                    end
+                  end
+                end
+
+              end
+              _log "   > #{resource} metadata", "JSONAPI::Doc::Parser"
+              _log metadata,  "JSONAPI::Doc::Parser"
+              metadata
+            end
+
+            def get_resource(line, indent = nil)
+              if indent.nil?
+                resource = /^((?<indent>\s*))?(?<name>[a-z]+[0-9|a-z|_]*?):\s*(#(?<meta>.*?))*$/.match(line)
+              else
+                resource = /^((?<indent>\s{#{indent}}))?(?<name>[a-z]+[0-9|a-z|_]*?):\s*(#(?<meta>.*?))*$/.match(line)
+              end
+              if resource
+                [ resource[:name], resource[:meta], resource[:indent] ]
+              else
+                [ nil, nil, nil ]
+              end
+            end
+            def get_jsonapi_attribute(line)
+              resource = /^(?<name>[a-z]+[0-9|a-z|_|-]*?):\s*(#(?<meta>.*?))*$/.match(line.strip)
+              if resource
+                [ resource[:name], resource[:meta] ]
+              else
+                [ nil, nil ]
+              end
+            end
+            def is_beginning_of_attribute_section?(line)
+              line = line.strip
+              line = line[1..line.length-1] if line.start_with?('#')
+              name, meta = get_jsonapi_attribute(line)
+              return true if name && name.to_sym == :attributes
+            end
+            def get_attribute(line)
+              attribute = /^(#\s*)?-\s*(?<name>[a-z]+[0-9|a-z|_]*?)(\s*:\s*)?(#(?<meta>.*?))*$/.match(line.strip)
+              if attribute
+                [ attribute[:name], attribute[:meta] ]
+              else
+                [ nil, nil ]
+              end
+            end
+            def get_metadata(line)
+              line = line.strip
+              attribute = get_attribute(line)
+              metadata = line.start_with?('#') ? line[1..line.length-1].strip : nil
+              tag = /^#\s*\[(?<tag>(\w|=|\s)+?)\]\s*$/.match(line)
+              if tag.nil?
+                example = /\((ex|Ex|default|Default):\s*(?<eg>.+?)\)/.match(line)
+                if metadata && attribute.first.nil? && metadata != 'attributes:'
+                  [ metadata, example ? example[:eg] : nil, nil ]
+                else
+                  [ nil, nil, nil ]
+                end
+              else
+                [ nil, nil, tag[:tag] ]
+              end
+            end
+            def get_value_of(attribute, line)
+              # First try to match a string value, between double quotes
+              data = /^#{attribute}:\s*(\"){1}(?<value>.*?)(\"){1}/.match(line.strip)
+              # Then try to match a non-string value
+              data = /^#{attribute}:\s*(?<value>.*?)(#(?<meta>.*?))*$/.match(line.strip) if data.nil?
+              data ? data[:value] : nil
+            end
+
+            def get_metadata_for(enumerable, index, object)
+              return if object.first.nil?
+              name = object.first.strip
+              data = []
+              example = nil
+              tags = []
+              if object[1].nil?
+                each_backwards(enumerable, index) do |line|
+                  m = get_metadata(line)
+                  if m.first
+                    data << m.first
+                    example = m[1] if m[1]
+                  else
+                    if m[2]
+                      tags << m[2]
+                    else
+                      break
+                    end
+                  end
+                end
+              else
+                data << object[1].strip
+              end
+              if data.any?
+                data.reverse!
+                _log "   > #{name} metadata", "JSONAPI::Doc::Parser"
+                _log data,  "JSONAPI::Doc::Parser"
+              else
+                data = nil
+                _log "   > #{name} has no metadata", "JSONAPI::Doc::Parser"
+              end
+              [ data, example, tags ]
+            end
+
+            def each_backwards(enumerable, index, &block)
+              while index > 0 do
+                 index = index - 1
+                 next if enumerable[index].strip.blank?
+                 block.call(enumerable[index])
+              end
+            end
+
+        end
+
+      end
+    end
+  end
+end