nexmo-oas-renderer 2.1.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Nexmo Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,103 @@
+# Nexmo OAS Renderer
+Sinatra application that provides a preview of how the OAS documents will be rendered within [Nexmo Developer](https://developer.nexmo.com/).
+
+* [Dependencies](#requirements)
+* [Installation and Usage](#installation-and-usage)
+    * [Using Docker](#using-docker)
+    * [As a standalone application](#as-a-standalone-application)
+    * [Mounted into a Rails application](#mounted-into-a-rails-application)
+    * [Specifying the path to the documents](#specifying-the-path-to-the-documents)
+* [Contributing](#contributing)
+* [License](#license)
+
+## Dependencies
+
+
+## Installation and Usage
+
+### Using Docker
+
+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
+```
+
+Alternatively, add the following to your `~/.bashrc` file and you'll be able to run `nexmo-oas-renderer`
+
+```
+function nexmo-oas-renderer() {
+  docker run --rm -p 4567:4567 -v `pwd`:/definitions -e 'OAS_PATH=/definitions' nexmodev/nexmo-oas-renderer:latest
+}
+```
+
+#### 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:
+
+``` shell
+$ gem install nexmo-oas-renderer
+```
+
+And simply run the executable with the corresponding env variables set (see [Note](#note)):
+``` shell
+$ nexmo-oas-renderer
+```
+
+Or, if you want to make code changes, just run the following command which will start the web server on http://localhost:9393:
+``` shell
+OAS_PATH=... bundle exec shotgun lib/nexmo/oas/renderer/config.ru
+```
+
+### Mounted into a Rails Application
+
+Add this to your application's `Gemfile`:
+
+```
+gem 'nexmo-oas-renderer', require: false
+```
+
+And then run `bundle install`.
+
+Require the gem in `config/environment.rb` as follows:
+
+``` ruby
+# Load the Rails application.
+require_relative 'application'
+
+require 'nexmo/oas/renderer'
+
+# Initialize the Rails application.
+Rails.application.initialize!
+```
+
+And finally mount the Sinatra app into your Rails application by adding the following line to `config/routes.rb`:
+
+``` ruby
+mount Nexmo::OAS::Renderer::API, at: '/api'
+```
+
+### Specifying the path to the documents
+
+This gem uses [dotenv](https://github.com/bkeepers/dotenv) to handle environment variables, so you should copy the `.env.example` provided by running:
+``` shell
+$ cp .env.example .env
+```
+and assign values to the corresponding variables.
+
+#### Note
+The env variable `OAS_PATH` indicates the path to the documents that will be rendered.
+
+## Contributing
+We ❤️ contributions from everyone! [Bug reports](https://github.com/Nexmo/nexmo-oas-renderer/issues), [bug fixes](https://github.com/Nexmo/nexmo-oas-renderer/pulls) and feedback on the library is always appreciated. Look at the [Contributor Guidelines](https://github.com/Nexmo/nexmo-oas-renderer/blob/master/CONTRIBUTING.md) for more information and please follow the [GitHub Flow](https://guides.github.com/introduction/flow/index.html).
+
+## License
+This project is under the [MIT LICENSE](https://github.com/Nexmo/nexmo-oas-renderer/blob/master/LICENSE).

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler/gem_tasks'
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+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.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/nexmo-oas-renderer

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'nexmo/oas/renderer'
+
+Nexmo::OAS::Renderer::API.run!

data/lib/nexmo/oas/engine.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Nexmo
+  module OAS
+    module Renderer
+      class Engine < ::Rails::Engine
+        config.assets.paths << "#{config.root}/lib/nexmo/oas/renderer/public/assets"
+      end
+    end
+  end
+end

data/lib/nexmo/oas/renderer.rb

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

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

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require 'sinatra/base'
+require 'active_support'
+require 'active_support/core_ext/array/conversions'
+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/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'
+
+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')]
+          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
+          include Helpers::Navigation
+          include Helpers::Summary
+          include Helpers::URL
+        end
+
+        def parse_params(extension)
+          extensions = extension.split('.')
+          case extensions.size
+          when 1
+            { definition: extensions.first }
+          when 2
+            if extensions.second.match?(/v\d+/)
+              { definition: extensions.first, version: extensions.second }
+            else
+              { definition: extensions.first, format: extensions.second }
+            end
+          when 3
+            { definition: extensions.first, version: extensions.second, format: extensions.last }
+          else
+            {}
+          end
+        end
+
+        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)
+          return unless defined?(NexmoDeveloper::Application)
+
+          pass unless OpenApiConstraint.match?(definition)
+        end
+
+        error Errno::ENOENT do
+          layout = defined?(NexmoDeveloper::Application) ? :'layouts/api.html' : false
+          not_found erb :'static/404', layout: layout
+        end
+
+        error Exception do
+          File.read("#{API.root}/public/500.html")
+        end
+
+        unless defined?(NexmoDeveloper::Application)
+          get '/' do
+            prefix = API.oas_path.to_s
+            @definitions = Dir.glob("#{prefix}/**/*.yml").map do |d|
+              d.gsub("#{prefix}/", '').gsub('.yml', '')
+            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
+          check_redirect!
+
+          parameters = parse_params(params[:definition])
+          definition = [parameters[:definition], parameters[:version]].compact.join('.')
+          check_oas_constraints!(definition)
+
+          @specification = Presenters::OpenApiSpecification.new(
+            definition_name: definition,
+            expand_responses: params.fetch(:expandResponses, nil)
+          )
+
+          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
+            erb :'open_api/show', layout: :'layouts/open_api'
+          end
+        end
+
+        def set_document
+          @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
+          set_document
+
+          @specification = Presenters::ApiSpecification.new(
+            document_name: @document,
+            code_language: @code_language
+          )
+
+          @navigation = Presenters::Navigation.new(
+            content: @specification.content,
+            title: @specification.side_navigation_title
+          )
+
+          if defined?(NexmoDeveloper::Application)
+            @content = @navigation.content
+            @side_navigation_title = @navigation.title
+
+            erb :'api/show', layout: :'layouts/api.html'
+          else
+            erb :'api/show', layout: :'layouts/api'
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative './app'
+require 'sass/plugin/rack'
+
+Sass::Plugin.options[:style] = :compressed
+use Sass::Plugin::Rack
+
+run Nexmo::OAS::Renderer::API

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

@@ -0,0 +1,138 @@
+terminal_programs:
+  curl:
+    weight: 1
+    label: cURL
+    lexer: sh
+    icon: curl
+    run_command: 'sh {filename}'
+  cli:
+    label: CLI
+    lexer: sh
+    linkable: false
+
+languages:
+  javascript:
+    weight: 2
+    label: JavaScript
+    lexer: javascript
+    icon: javascript
+    dependencies:
+      - 'nexmo'
+
+  node:
+    weight: 2
+    label: Node.js
+    lexer: javascript
+    icon: node
+    dependencies:
+      - 'nexmo'
+    run_command: 'node {filename}'
+
+  java:
+    weight: 3
+    label: Java
+    lexer: java
+    unindent: true
+    icon: java
+    dependencies:
+      - 'com.nexmo:client:@latest'
+
+  dotnet:
+    weight: 4
+    label: .NET
+    lexer: c#
+    unindent: true
+    icon: dotnet
+    dependencies:
+      - 'Nexmo.Csharp.Client'
+  csharp:
+    weight: 4
+    label: .NET
+    lexer: c#
+    unindent: true
+    icon: dotnet
+    dependencies:
+      - 'Nexmo.Csharp.Client'
+
+  php:
+    weight: 5
+    label: PHP
+    lexer: php
+    icon: php
+    dependencies:
+      - 'nexmo/client'
+    run_command: 'php {filename}'
+
+  python:
+    weight: 6
+    label: Python
+    lexer: python
+    icon: python
+    dependencies:
+      - 'nexmo'
+    run_command: 'python {filename}'
+
+  ruby:
+    weight: 7
+    label: Ruby
+    lexer: ruby
+    icon: ruby
+    dependencies:
+      - 'nexmo'
+    run_command: 'ruby {filename}'
+
+  kotlin:
+    weight: 8
+    label: Kotlin
+    lexer: java
+    icon: android
+    dependencies: []
+
+  android:
+    weight: 9
+    label: Java
+    lexer: java
+    icon: android
+    dependencies: []
+
+  swift:
+    weight: 10
+    label: Swift
+    lexer: swift
+    icon: ios
+    dependencies: []
+
+  objective_c:
+    weight: 11
+    label: Objective-C
+    lexer: objective_c
+    icon: ios
+    dependencies: []
+
+platforms:
+  ios:
+    languages:
+      - swift
+      - objective_c
+  android:
+    languages:
+      - java
+  web:
+    languages:
+      - javascript
+
+data:
+  ncco:
+    label: NCCO
+    lexer: json
+    linkable: false
+  json:
+    weight: 1
+    label: JSON
+    lexer: json
+    linkable: false
+  xml:
+    weight: 2
+    label: XML
+    lexer: xml
+    linkable: false