nexmo-oas-renderer 0.11.3 → 2.1.2

data/lib/nexmo/oas/renderer/app.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'sinatra/base'
 require 'active_support'
 require 'active_support/core_ext/array/conversions'
@@ -5,15 +7,16 @@ require 'active_support/core_ext/string/output_safety'
 require 'active_model'
 require 'nexmo_markdown_renderer'
 
-require_relative'./decorators/response_parser_decorator'
-require_relative'./presenters/api_specification'
-require_relative'./presenters/open_api_specification'
-require_relative'./presenters/navigation'
-require_relative'./presenters/response_tabs'
-require_relative'./helpers/render'
-require_relative'./helpers/navigation'
-require_relative'./helpers/summary'
-require_relative'./helpers/url'
+require_relative './decorators/response_parser_decorator'
+require_relative './presenters/api_specification'
+require_relative './presenters/open_api_specification'
+require_relative './presenters/navigation'
+require_relative './presenters/request_body_raw'
+require_relative './presenters/response_tabs'
+require_relative './helpers/render'
+require_relative './helpers/navigation'
+require_relative './helpers/summary'
+require_relative './helpers/url'
 
 require 'dotenv/load'
 
@@ -21,18 +24,17 @@ module Nexmo
   module OAS
     module Renderer
       class API < Sinatra::Base
-
         Tilt.register Tilt::ERBTemplate, 'html.erb'
 
         if defined?(NexmoDeveloper::Application)
-          view_paths = [views, NexmoDeveloper::Application.root.join("app", "views")]
+          view_paths = [views, NexmoDeveloper::Application.root.join('app', 'views')]
           set :views, view_paths
         end
 
         set :mustermann_opts, { type: :rails }
         set :oas_path, (ENV['OAS_PATH'] || './')
         set :bind, '0.0.0.0'
-        set :github_path, Proc.new { load_business_yaml }
+        set :github_path, (proc { load_business_yaml })
 
         helpers do
           include Helpers::Render
@@ -45,9 +47,9 @@ module Nexmo
           extensions = extension.split('.')
           case extensions.size
           when 1
-            { definition: extensions.first}
+            { definition: extensions.first }
           when 2
-            if extensions.second.match? /v\d+/
+            if extensions.second.match?(/v\d+/)
               { definition: extensions.first, version: extensions.second }
             else
               { definition: extensions.first, format: extensions.second }
@@ -60,29 +62,29 @@ module Nexmo
         end
 
         def self.load_business_yaml
-          if defined?(NexmoDeveloper::Application) && !File.exist?("#{Rails.configuration.docs_base_path}/config/business_info.yml")
-            raise "Application requires a 'config/business_info.yml' file to be defined inside the documentation path."
-          elsif defined?(NexmoDeveloper::Application) && File.exist?("#{Rails.configuration.docs_base_path}/config/business_info.yml")
+          raise "Application requires a 'config/business_info.yml' file to be defined inside the documentation path." if defined?(NexmoDeveloper::Application) && !File.exist?("#{Rails.configuration.docs_base_path}/config/business_info.yml")
+
+          if defined?(NexmoDeveloper::Application) && File.exist?("#{Rails.configuration.docs_base_path}/config/business_info.yml")
             @url ||= begin
               config = YAML.load_file("#{Rails.configuration.docs_base_path}/config/business_info.yml")
               config['oas_url']
             end
           else
-            "https://www.github.com/nexmo/api-specification/blob/master/definitions"
+            'https://www.github.com/nexmo/api-specification/blob/master/definitions'
           end
         end
 
         def check_redirect!
-          if defined?(NexmoDeveloper::Application)
-            redirect_path = Redirector.find(request)
-            redirect(redirect_path) if redirect_path
-          end
+          return unless defined?(NexmoDeveloper::Application)
+
+          redirect_path = Redirector.find(request)
+          redirect(redirect_path) if redirect_path
         end
 
         def check_oas_constraints!(definition)
-          if defined?(NexmoDeveloper::Application)
-            pass unless OpenApiConstraint.match?(definition)
-          end
+          return unless defined?(NexmoDeveloper::Application)
+
+          pass unless OpenApiConstraint.match?(definition)
         end
 
         error Errno::ENOENT do
@@ -96,21 +98,44 @@ module Nexmo
 
         unless defined?(NexmoDeveloper::Application)
           get '/' do
-            prefix = "#{API.oas_path}"
+            prefix = API.oas_path.to_s
             @definitions = Dir.glob("#{prefix}/**/*.yml").map do |d|
               d.gsub("#{prefix}/", '').gsub('.yml', '')
-            end.sort.reject { |d| d.include? 'common/' }
+            end
+
+            @definitions = @definitions.sort.reject { |d| d.include? 'common/' }
             erb :'api/index', layout: false
           end
         end
 
         def set_code_language
           return if params[:code_language] == 'templates'
+
           @code_language = params[:code_language]
         end
 
+        def set_theme
+          persisted_theme = nil
+
+          if defined?(NexmoDeveloper::Application)
+            session[:persisted_theme] = params[:theme] if params[:theme]
+            persisted_theme = session[:persisted_theme]
+          end
+
+          @theme = params[:theme] || persisted_theme
+
+          @theme = 'light' unless %w[light dark].include?(@theme)
+
+          @theme_light = @theme == 'light'
+
+          alternate_theme = @theme == 'light' ? 'dark' : 'light'
+          @theme_link = "#{request.path_info}?theme=#{alternate_theme}"
+          @theme_link = "/api#{@theme_link}" if defined?(NexmoDeveloper::Application)
+        end
+
         before do
           set_code_language
+          set_theme
         end
 
         get '(/api)/*definition' do
@@ -122,30 +147,30 @@ module Nexmo
 
           @specification = Presenters::OpenApiSpecification.new(
             definition_name: definition,
-            expand_responses: params.fetch(:expandResponses, nil),
+            expand_responses: params.fetch(:expandResponses, nil)
           )
 
-          if ['yml', 'json'].include?(parameters[:format])
-            send_file @specification.definition.path, disposition: :attachment
+          if %w[yml json].include?(parameters[:format])
+            next send_file @specification.definition.path, disposition: :attachment
+          end
+
+          if defined?(NexmoDeveloper::Application)
+            erb :'open_api/show', layout: :'layouts/open-api.html'
           else
-            if defined?(NexmoDeveloper::Application)
-              erb :'open_api/show', layout: :'layouts/page-full.html'
-            else
-              erb :'open_api/show', layout: :'layouts/open_api'
-            end
+            erb :'open_api/show', layout: :'layouts/open_api'
           end
         end
 
         def set_document
-          if params[:code_language] == 'templates'
-            @document = 'verify/templates'
-          elsif params[:code_language] == 'ncco'
-            @document = 'voice/ncco'
-          elsif ::Nexmo::Markdown::CodeLanguage.exists?(params[:code_language])
-            @document = params[:document]
-          else
-            @document = "#{params[:document]}/#{params[:code_language]}"
-          end
+          @document = if params[:code_language] == 'templates'
+                        'verify/templates'
+                      elsif params[:code_language] == 'ncco'
+                        'voice/ncco'
+                      elsif ::Nexmo::Markdown::CodeLanguage.exists?(params[:code_language])
+                        params[:document]
+                      else
+                        "#{params[:document]}/#{params[:code_language]}"
+                      end
         end
 
         get '(/api)/*document(/:code_language)' do
@@ -158,7 +183,7 @@ module Nexmo
 
           @navigation = Presenters::Navigation.new(
             content: @specification.content,
-            title: @specification.side_navigation_title,
+            title: @specification.side_navigation_title
           )
 
           if defined?(NexmoDeveloper::Application)

data/lib/nexmo/oas/renderer/config.ru

@@ -1,5 +1,7 @@
-require_relative "./app"
-require "sass/plugin/rack"
+# frozen_string_literal: true
+
+require_relative './app'
+require 'sass/plugin/rack'
 
 Sass::Plugin.options[:style] = :compressed
 use Sass::Plugin::Rack

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rouge'
 require 'neatjson'
 require_relative '../services/oas_parser'
@@ -8,43 +10,41 @@ module Nexmo
       class ResponseParserDecorator < ::OasParser::ResponseParser
         def formatted_json
           JSON.neat_generate(parse, {
-            wrap: true,
-            after_colon: 1,
-          })
+                               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 = $1
-            indentation_plus_one = "#{$1}  "
-            opening_tag = $2
-            content = $3
-            closing_tag = $4
+          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
+          xml_string.gsub('<', '&lt;')
         end
 
-        def html(format = 'application/json', xml_options: nil)
-          formatter = Rouge::Formatters::HTML.new
-
+        def html(format = 'application/json', xml_options: nil, theme_light: nil)
           case format
           when 'application/json'
-            lexer = Rouge::Lexer.find('json')
-            highlighted_response = formatter.format(lexer.lex(formatted_json))
+            language = 'json'
+            response = formatted_json
           when 'text/xml', 'application/xml'
-            lexer = Rouge::Lexer.find('xml')
-            highlighted_response = formatter.format(lexer.lex(formatted_xml(xml_options)))
+            language = 'xml'
+            response = formatted_xml(xml_options)
           end
 
           output = <<~HEREDOC
-      <pre class="language-#{lexer && lexer.tag || 'json'} Vlt-prism--dark Vlt-prism--copy-disabled"><code>#{highlighted_response}</code></pre>
+            <pre class="pre-wrap language-#{language}  #{theme_light ? 'Vlt-prism--dark' : ''} Vlt-prism--copy-disabled"><code>#{response}</code></pre>
           HEREDOC
 
           output

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

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
 module Nexmo
   module OAS
     module Renderer
       module Helpers
         module Navigation
-
           HEADING_TAG_DEPTHS = {
             'h0' => 0,
             'h1' => 1,
@@ -58,7 +59,6 @@ module Nexmo
           def build_document(content)
             Nokogiri::HTML::DocumentFragment.parse(content)
           end
-
         end
       end
     end

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

@@ -1,9 +1,10 @@
+# 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)

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Nexmo
   module OAS
     module Renderer
@@ -17,9 +19,10 @@ module Nexmo
             operation_id = operation_id.gsub(/(_|-)/, ' ').titleize
 
             # Some terms need to be capitalised all the time
-            uppercase_array = ['SMS', 'DTMF']
+            uppercase_array = %w[SMS DTMF]
             operation_id.split(' ').map do |c|
               next c.upcase if uppercase_array.include?(c.upcase)
+
               c
             end.join(' ')
           end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Nexmo
   module OAS
     module Renderer

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

@@ -1,20 +1,29 @@
+# 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
-            "api/#{@document_name}"
+            if defined?(NexmoDeveloper::Application)
+              "#{Rails.configuration.docs_base_path}/api/#{@document_name}"
+            else
+              "api/#{@document_name}"
+            end
           end
 
           def document_path
-            "_api/#{@document_name}.md"
+            if defined?(NexmoDeveloper::Application)
+              "#{Rails.configuration.docs_base_path}/_api/#{@document_name}.md"
+            else
+              "_api/#{@document_name}.md"
+            end
           end
 
           def document

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative './response_format'
 
 module Nexmo

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Nexmo
   module OAS
     module Renderer
@@ -12,6 +14,7 @@ module Nexmo
             # 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
 
@@ -25,6 +28,7 @@ module Nexmo
             # 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

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative '../helpers/navigation'
 
 module Nexmo

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'forwardable'
 require_relative './endpoint'
 require_relative './response_format'
@@ -9,7 +11,6 @@ module Nexmo
   module OAS
     module Renderer
       module Presenters
-
         class OpenApiSpecification
           extend Forwardable
 
@@ -30,9 +31,11 @@ module Nexmo
           end
 
           def definition_errors
+            return unless errors?
+
             @definition_errors ||= Nexmo::Markdown::Renderer.new.call(
               File.read("#{API.oas_path}/../../errors/#{@definition_name}.md")
-            ) if errors?
+            )
           end
 
           def definition

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