nexmo-oas-renderer 2.1.1

data/lib/nexmo/oas/renderer/config/dynamic_content.yml

@@ -0,0 +1 @@
+dynamic_content_example: the future

data/lib/nexmo/oas/renderer/decorators/response_parser_decorator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'rouge'
+require 'neatjson'
+require_relative '../services/oas_parser'
+
+module Nexmo
+  module OAS
+    module Renderer
+      class ResponseParserDecorator < ::OasParser::ResponseParser
+        def formatted_json
+          JSON.neat_generate(parse, {
+                               wrap: true,
+                               after_colon: 1,
+                             })
+        end
+
+        def formatted_xml(xml_options = {})
+          xml_options[:root] = xml_options['name'] if xml_options
+          xml_string = xml(xml_options)
+          xml_string.gsub!(%r{^(\s+?)(<(?:\w|=|"|_|\s)+?>)(.+?)(</.+?>)}).each do |s|
+            indentation = Regexp.last_match(1)
+            indentation_plus_one = "#{Regexp.last_match(1)}  "
+            opening_tag = Regexp.last_match(2)
+            content = Regexp.last_match(3)
+            closing_tag = Regexp.last_match(4)
+
+            next(s) if (indentation.size + opening_tag.size + content.size) < 60
+
+            next "#{indentation}#{opening_tag}\n#{indentation_plus_one}#{content}\n#{indentation}#{closing_tag}"
+          end
+
+          xml_string.gsub('<', '&lt;')
+        end
+
+        def html(format = 'application/json', xml_options: nil, theme_light: nil)
+          case format
+          when 'application/json'
+            language = 'json'
+            response = formatted_json
+          when 'text/xml', 'application/xml'
+            language = 'xml'
+            response = formatted_xml(xml_options)
+          end
+
+          output = <<~HEREDOC
+            <pre class="pre-wrap language-#{language}  #{theme_light ? 'Vlt-prism--dark' : ''} Vlt-prism--copy-disabled"><code>#{response}</code></pre>
+          HEREDOC
+
+          output
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/helpers/navigation.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Nexmo
+  module OAS
+    module Renderer
+      module Helpers
+        module Navigation
+          HEADING_TAG_DEPTHS = {
+            'h0' => 0,
+            'h1' => 1,
+            'h2' => 2,
+            'h3' => 3,
+            'h4' => 4,
+            'h5' => 5,
+            'h6' => 6,
+          }.freeze
+
+          def navigation_from_content(content:, title: nil)
+            content = "<h0 class='injected'>#{title}</h0>\n" + content if title
+            document = build_document(content)
+
+            nodes = ['<ul class="Vlt-sidemenu Vlt-sidemenu--rounded Vlt-sidemenu--flat navigation js-navigation">']
+            last_node = nil
+
+            document.css('.reveal').remove
+
+            document.css('h0,h2,h3,h4,h5,h6').each do |heading|
+              # If it's a header within tabbed content (including Code Snippets) we don't want to treat
+              # the header as a navigation item in the sidebar
+              next unless heading.ancestors('.Vlt-tabs').empty?
+
+              # Same with callouts
+              next unless heading.ancestors('.Vlt-callout').empty?
+
+              if last_node.nil? || heading.name == last_node.name
+                # Do nothing (cleaner than adding wrapping further conditions)
+              elsif heading.name >= last_node.name # e.g. h2 -> h3
+                nodes << '<ul>'
+              else # e.g. h4 -> h2
+                (HEADING_TAG_DEPTHS[last_node.name] - HEADING_TAG_DEPTHS[heading.name]).times do
+                  nodes << '</li></ul>'
+                end
+              end
+
+              nodes << <<~HEREDOC
+                <li>
+                <a class="Vlt-sidemenu__link Vlt-grey-darker" href="##{heading.attributes['id']}" data-scrollspy-id="#{heading['data-id']}">
+                  #{heading.text}
+                </a>
+              HEREDOC
+              last_node = heading
+            end
+            nodes << '</li></ul>'
+            nodes.join("\n").html_safe
+          end
+
+          private
+
+          def build_document(content)
+            Nokogiri::HTML::DocumentFragment.parse(content)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/helpers/render.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Nexmo
+  module OAS
+    module Renderer
+      module Helpers
+        module Render
+          def find_template(views, name, engine, &block)
+            Array(views).each do |v|
+              super(v, name, engine, &block)
+            end
+          end
+
+          def render(*args)
+            if args.length > 2
+              super
+            else
+              ApplicationController.renderer.render(*args)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/helpers/summary.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Nexmo
+  module OAS
+    module Renderer
+      module Helpers
+        module Summary
+          def normalize_summary_title(summary, operation_id)
+            # return summary early if provided
+            return summary unless summary.nil?
+
+            # If the operation ID is camelCase,
+            if operation_id.match?(/^[a-zA-Z]\w+(?:[A-Z]\w+){1,}/x)
+              # Use the rails `.underscore` method to convert someString to some_string
+              operation_id = operation_id.underscore
+            end
+
+            # Replace snake_case and kebab-case with spaces and titelize the string
+            operation_id = operation_id.gsub(/(_|-)/, ' ').titleize
+
+            # Some terms need to be capitalised all the time
+            uppercase_array = %w[SMS DTMF]
+            operation_id.split(' ').map do |c|
+              next c.upcase if uppercase_array.include?(c.upcase)
+
+              c
+            end.join(' ')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/helpers/url.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Nexmo
+  module OAS
+    module Renderer
+      module Helpers
+        module URL
+          def parameter_values(enum)
+            enum.map { |value| "<code>#{value}</code>" }.to_sentence(last_word_connector: ' or ', two_words_connector: ' or ')
+          end
+
+          def canonical_path
+            request.path.chomp("/#{@code_language}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/presenters/api_specification.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Nexmo
+  module OAS
+    module Renderer
+      module Presenters
+        class ApiSpecification
+          def initialize(document_name:, code_language: nil)
+            @document_name = document_name
+            @code_language = code_language
+          end
+
+          def side_navigation
+            if defined?(NexmoDeveloper::Application)
+              "#{Rails.configuration.docs_base_path}/api/#{@document_name}"
+            else
+              "api/#{@document_name}"
+            end
+          end
+
+          def document_path
+            if defined?(NexmoDeveloper::Application)
+              "#{Rails.configuration.docs_base_path}/_api/#{@document_name}.md"
+            else
+              "_api/#{@document_name}.md"
+            end
+          end
+
+          def document
+            @document ||= File.read(document_path)
+          end
+
+          def frontmatter
+            @frontmatter ||= YAML.safe_load(document)
+          end
+
+          def side_navigation_title
+            @side_navigation_title ||= frontmatter.fetch('api')
+          end
+
+          def document_title
+            @document_title ||= "#{side_navigation_title} > #{frontmatter.fetch('title')}"
+          end
+
+          def content
+            options = {}
+            options.merge(code_language: @code_language) if @code_language
+            @content ||= Nexmo::Markdown::Renderer.new(options).call(document)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/presenters/endpoint.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative './response_format'
+
+module Nexmo
+  module OAS
+    module Renderer
+      module Presenters
+        class Endpoint
+          def initialize(endpoint)
+            @endpoint = endpoint
+          end
+
+          def formats
+            @formats ||= ResponseFormat.new(@endpoint.responses).extract
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/presenters/groups.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Nexmo
+  module OAS
+    module Renderer
+      module Presenters
+        class Groups
+          def initialize(definition)
+            @definition = definition
+          end
+
+          def groups
+            tags = @definition.raw['tags']
+            # For now we only use the first tag in the list as an equivalent for the old x-group functionality
+            @groups = @definition.endpoints.group_by do |endpoint|
+              next nil unless tags
+
+              endpoint.raw['tags']&.first
+            end
+
+            # We want to use the order in which the tags are defined in the definition, so iterate over the tags
+            # and store the index against the tag name. We'll use this later for sorting
+            ordering = {}
+            tags&.each_with_index do |tag, index|
+              ordering[tag['name'].capitalize] = index
+            end
+
+            # Sort by the order in which they're defined in the definition
+            @groups = @groups.sort_by do |name, _|
+              next -1 if name.nil?
+
+              ordering[name.capitalize] || 999
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/presenters/navigation.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative '../helpers/navigation'
+
+module Nexmo
+  module OAS
+    module Renderer
+      module Presenters
+        class Navigation
+          include Helpers::Navigation
+
+          attr_reader :title, :content
+
+          def initialize(content:, title: nil)
+            @content = content
+            @title   = title
+          end
+
+          def navigation_from_content
+            super(content: @content, title: @title)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/presenters/open_api_specification.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require_relative './endpoint'
+require_relative './response_format'
+require_relative './groups'
+require_relative './versions'
+require_relative '../services/open_api_definition_resolver'
+
+module Nexmo
+  module OAS
+    module Renderer
+      module Presenters
+        class OpenApiSpecification
+          extend Forwardable
+
+          attr_reader :definition_name
+
+          def_delegators :@versions, :current_version, :available_versions
+          def_delegators :@groups, :groups
+
+          def initialize(definition_name:, expand_responses:)
+            @definition_name  = definition_name
+            @expand_responses = expand_responses
+            @versions         = Versions.new(definition_name)
+            @groups           = Groups.new(definition)
+          end
+
+          def errors?
+            File.exist?("#{API.oas_path}/../../errors/#{@definition_name}.md")
+          end
+
+          def definition_errors
+            return unless errors?
+
+            @definition_errors ||= Nexmo::Markdown::Renderer.new.call(
+              File.read("#{API.oas_path}/../../errors/#{@definition_name}.md")
+            )
+          end
+
+          def definition
+            @definition ||= OpenApiDefinitionResolver.find(@definition_name)
+          end
+
+          def auto_expand_responses
+            @expand_responses
+          end
+
+          def formats
+            @formats ||= ResponseFormat.to_dropdown(endpoints.flat_map(&:formats).uniq)
+          end
+
+          private
+
+          def endpoints
+            @endpoints ||= definition.endpoints.map { |e| Endpoint.new(e) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer/presenters/request_body_raw.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Nexmo
+  module OAS
+    module Renderer
+      module Presenters
+        class RequestBodyRaw
+          def initialize(parameters, options = {}, endpoint = nil)
+            @parameters = parameters
+            @options = options
+            @endpoint = endpoint
+          end
+
+          def to_format(format)
+            return to_urlencoded if format == 'application/x-www-form-urlencoded'
+
+            to_json
+          end
+
+          def to_urlencoded
+            example = ''
+            body = URI.encode_www_form(generate_request)
+            if @endpoint
+              servers = @endpoint.path.servers || @endpoint.definition.servers
+              path = @endpoint.path.path.gsub(/\{(.+?)\}/, ':\1')
+              uri = URI("#{servers[0]['url']}#{path}")
+              example += "#{@endpoint.method.upcase} #{uri.path} HTTP/1.1\n"
+              example += "Host: #{uri.host} \n"
+              example += "Content-Type: application/x-www-form-urlencoded\n"
+              example += "Content-Length: #{body.length}\n"
+              example += "\n"
+            end
+            example += body
+            example
+          end
+
+          def to_json(*_args)
+            JSON.pretty_generate(generate_request)
+          end
+
+          def generate_request(parameters = nil, options = nil)
+            parameters ||= @parameters
+            options ||= @options
+            output = {}
+
+            parameters.each do |parameter|
+              next if options['required_only'] && optional?(parameter, options['required'])
+
+              parameter_name = name(parameter)
+              param = parameter
+
+              # This is all required to handle an edge case where parameter.name is an OasParser::Property
+              # Which happens when you use a oneOf inside items in a property.
+              # I believe this is a bug, but it's a BC break in the parser
+
+              if parameter_name.instance_of?(OasParser::Property)
+                parameter_name = parameter.owner.name
+                param = OasParser::Parameter.new(parameter_name, parameter.schema)
+              end
+
+              if param.raw['items'] && param.raw['example']
+                output[parameter_name] = param.raw['example']
+              elsif param.raw['items'] && param.raw['items']['oneOf']
+                param = param.raw['items']['oneOf'][0]
+                output[parameter_name] = [generate_request(properties(param).map(&:name))]
+              elsif collection?(param) && properties?(param)
+                nested_output = generate_request(properties(param))
+                next unless nested_output.keys.length.positive?
+
+                nested_output = [nested_output] if param.array?
+                output[parameter_name] = nested_output
+              else
+                ex = example(param)
+                next unless ex
+
+                if ex.is_a?(String)
+                  # Remove line breaks
+                  ex = ex.gsub('<br />', ' ')
+                end
+                output[parameter_name] = ex
+              end
+            end
+            output
+          end
+
+          def items(parameter)
+            return parameter['items'] unless parameter.respond_to?(:items)
+
+            parameter.items
+          end
+
+          def example(parameter)
+            return parameter['example'] unless parameter.respond_to?(:example)
+
+            parameter.example
+          end
+
+          def name(parameter)
+            return parameter['name'] unless parameter.respond_to?(:name)
+
+            parameter.name
+          end
+
+          def properties(parameter)
+            return parameter['properties'] unless parameter.respond_to?(:properties)
+
+            parameter.properties
+          end
+
+          def array?(parameter)
+            return parameter['items'] unless parameter.respond_to?(:array?)
+
+            parameter.array?
+          end
+
+          def collection?(parameter)
+            return parameter['properties'] unless parameter.respond_to?(:collection?)
+
+            parameter.collection?
+          end
+
+          def properties?(parameter)
+            return parameter['properties'] unless parameter.respond_to?(:collection?)
+
+            parameter.properties.size.positive?
+          end
+
+          def optional?(parameter, allow_list)
+            return false if allow_list&.include?(name(parameter))
+
+            return false unless parameter.respond_to?(:required)
+
+            return false unless parameter.schema
+
+            !parameter.required
+          end
+        end
+      end
+    end
+  end
+end