nexmo-oas-renderer 0.10.0 → 2.0.0

data/README.md

@@ -19,6 +19,8 @@ Sinatra application that provides a preview of how the OAS documents will be ren
 
 You can run using Docker and it will serve the current directory (this will usually be the api-specification repo):
 
+#### Mac/Linux
+
 ```bash
 docker run --rm -p 4567:4567 -v `pwd`:/definitions -e 'OAS_PATH=/definitions' nexmodev/nexmo-oas-renderer:latest
 ```
@@ -31,6 +33,12 @@ function nexmo-oas-renderer() {
 }
 ```
 
+#### Windows
+
+```ps
+docker run --rm -p 4567:4567 -v %CD%:/definitions -e 'OAS_PATH=/definitions' nexmodev/nexmo-oas-renderer:latest
+```
+
 ### As a standalone application
 
 Install the gem:

data/Rakefile

@@ -1,2 +1,2 @@
-require "bundler/gem_tasks"
-task :default => :spec
+require 'bundler/gem_tasks'
+task default: :spec

data/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "nexmo/oas/renderer"
+require 'bundler/setup'
+require 'nexmo/oas/renderer'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +10,5 @@ require "nexmo/oas/renderer"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/lib/nexmo/oas/engine.rb

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

data/lib/nexmo/oas/renderer.rb

@@ -1,9 +1,9 @@
-require "nexmo/oas/renderer/version"
-require "nexmo/oas/renderer/app"
+# frozen_string_literal: true
 
-if defined?(NexmoDeveloper::Application)
-  require "nexmo/oas/engine"
-end
+require 'nexmo/oas/renderer/version'
+require 'nexmo/oas/renderer/app'
+
+require 'nexmo/oas/engine' if defined?(NexmoDeveloper::Application)
 
 module Nexmo
   module OAS

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,17 +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 { load_business_yaml })
 
         helpers do
           include Helpers::Render
@@ -44,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 }
@@ -58,17 +61,30 @@ module Nexmo
           end
         end
 
-        def check_redirect!
-          if defined?(NexmoDeveloper::Application)
-            redirect_path = Redirector.find(request)
-            redirect(redirect_path) if redirect_path
+        def self.load_business_yaml
+          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'
           end
         end
 
+        def check_redirect!
+          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
@@ -82,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
@@ -108,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
@@ -144,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,9 +1,10 @@
+# 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

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