nexmo-oas-renderer 0.1.0

data/lib/nexmo/oas/renderer/services/open_api_definition_resolver.rb

@@ -0,0 +1,33 @@
+require_relative './oas_parser'
+
+module Nexmo
+  module OAS
+    module Renderer
+      class OpenApiDefinitionResolver
+        def self.find(name)
+          path = paths(name).detect do |p|
+            break p if File.file? p
+          end
+
+          return resolve(path) if path
+
+          raise "Could not find definition '#{name}' in '#{API.oas_path}'"
+        end
+
+        def self.paths(name)
+          ['json', 'yaml', 'yml'].map do |format|
+            path(name, format)
+          end
+        end
+
+        def self.path(name, format)
+          "#{API.oas_path}/definitions/#{name}.#{format}"
+        end
+
+        def self.resolve(path)
+          OasParser::Definition.resolve(path)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+module Nexmo
+  module OAS
+    module Renderer
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/nexmo/oas/renderer/views/api/show.erb

@@ -0,0 +1 @@
+<%= @specification.content.html_safe %>

data/lib/nexmo/oas/renderer/views/code_snippets/_application_messages_dispatch.html.erb

@@ -0,0 +1,9 @@
+<div class="Vlt-box Vlt-box--lesspadding Nxd-accordion-emphasis">
+  <h5 class="Vlt-js-accordion__trigger Vlt-accordion__trigger" data-accordion="acc<%= id %>" tabindex="0">
+    <%= app['use_existing'] ? 'Use your existing application' : 'Create an application' %>
+  </h5>
+
+  <div id="acc<%=id %>"  class="Vlt-js-accordion__content Vlt-accordion__content Vlt-accordion__content--noborder">
+    If you do not have an application you can <a href="/messages/code-snippets/create-an-application">create one</a>. Make sure you also <a href="/messages/code-snippets/configure-webhooks">configure your webhooks</a>.
+  </div>
+</div>

data/lib/nexmo/oas/renderer/views/code_snippets/_application_rtc.html.erb

@@ -0,0 +1,41 @@
+<div class="Vlt-box Vlt-box--lesspadding Nxd-accordion-emphasis">
+    <h5 class="Vlt-js-accordion__trigger Vlt-accordion__trigger" data-accordion="acc<%= id %>" tabindex="0">
+        Create an application
+    </h5>
+
+    <div id="acc<%=id %>" class="Vlt-js-accordion__content Vlt-accordion__content Vlt-accordion__content--noborder">
+        <p>A Nexmo application contains the required configuration for your project. You can create an application
+            using the <a href="https://github.com/Nexmo/nexmo-cli">Nexmo CLI</a> (see below) or <a href="https://dashboard.nexmo.com/voice/create-application">via
+                the dashboard</a>. To learn more about applications <a href="/concepts/guides/applications">see our
+                Nexmo concepts guide</a>.</p>
+        <h4>Install the CLI</h4>
+        <pre class="highlight shell"><code>$ npm install -g nexmo-cli</code></pre>
+
+        <h4>Create an application</h4>
+        <p>Once you have the CLI installed you can use it to create a Nexmo application. Run the following command and
+            make a note of the application ID that it returns. This is the value to use in <code>NEXMO_APPLICATION_ID</code>
+            in the example below. It will also create <code>private.key</code> in the current directory which you will
+            need in the <em>Initialize your dependencies</em> step</p>
+
+        <% unless app['disable_ngrok'] %>
+        <p>Nexmo needs to connect to your local machine to access your <code>answer_url</code>. We recommend using <a
+                href="https://www.nexmo.com/blog/2017/07/04/local-development-nexmo-ngrok-tunnel-dr/">ngrok</a> to do
+            this. Make sure to change <code>demo.ngrok.io</code> in the examples below to your own ngrok URL.</p>
+        <% end %>
+
+        <pre class="highlight shell"><code>$ nexmo app:create "<%=app['name'] %>" <%=app['answer_url'] %> <%=app['event_url'] %> --keyfile=private.key --type=rtc</code></pre>
+        
+        <h4>Or to use your existing Nexmo application</h4>
+
+        <p>You will need to use an existing Nexmo application and
+            authenticate a User in order to achieve results here.</p>
+        <p>See the <a href="https://developer.nexmo.com/conversation/overview">Conversation API docs</a>
+            for information
+            on how to create an Application and Users on your backend server.</p>
+        <p>Alternatively you can review the <a href="https://developer.nexmo.com/tutorials/client-sdk-generate-test-credentials">tutorial
+                on getting started with generating an Application and
+                credentials</a>.</p>
+    </div>
+
+
+</div>

data/lib/nexmo/oas/renderer/views/code_snippets/_application_voice.html.erb

@@ -0,0 +1,24 @@
+<div class="Vlt-box Vlt-box--lesspadding Nxd-accordion-emphasis">
+    <h5 class="Vlt-js-accordion__trigger Vlt-accordion__trigger" data-accordion="acc<%= id %>" tabindex="0">
+        <%= app['use_existing'] ? 'Use your existing application' : 'Create an application' %>
+    </h5>
+
+    <div id="acc<%=id %>"  class="Vlt-js-accordion__content Vlt-accordion__content Vlt-accordion__content--noborder">
+        <% if app['use_existing'] %>
+            <p><%= app['use_existing'] %></p>
+        <% else %>
+            <p>A Nexmo application contains the required configuration for your project. You can create an application using the <a href="https://github.com/Nexmo/nexmo-cli">Nexmo CLI</a> (see below) or <a href="https://dashboard.nexmo.com/voice/create-application">via the dashboard</a>. To learn more about applications <a href="/concepts/guides/applications">see our Nexmo concepts guide</a>.</p>
+            <h4>Install the CLI</h4>
+            <pre class="highlight bash dependencies"><code>npm install -g nexmo-cli</code></pre>
+
+            <h4>Create an application</h4>
+            <p>Once you have the CLI installed you can use it to create a Nexmo application. Run the following command and make a note of the application ID that it returns. This is the value to use in <code>NEXMO_APPLICATION_ID</code> in the example below. It will also create <code>private.key</code> in the current directory which you will need in the <em>Initialize your dependencies</em> step</p>
+
+            <% unless app['disable_ngrok'] %>
+                <p>Nexmo needs to connect to your local machine to access your <code>answer_url</code>. We recommend using <a href="https://www.nexmo.com/blog/2017/07/04/local-development-nexmo-ngrok-tunnel-dr/">ngrok</a> to do this. Make sure to change <code>demo.ngrok.io</code> in the examples below to your own ngrok URL.</p>
+            <% end %>
+
+            <pre class="highlight bash dependencies"><code>nexmo app:create "<%=app['name'] %>" <%=app['answer_url'] %> <%=app['event_url'] %> --keyfile private.key</code></pre>
+        <% end %>
+    </div>
+</div>

data/lib/nexmo/oas/renderer/views/code_snippets/_code_only.html.erb

@@ -0,0 +1,6 @@
+<div class="copy-wrapper">
+  <div class="copy-button" data-lang="<%= lang %>" data-block="<%= config['source'] %>" data-section="code">
+    <%= octicon "clippy", :class => 'top left' %> <span>Copy to Clipboard</span>
+  </div>
+  <pre class="highlight <%= lexer.tag %> main-code"><code><%= highlighted_code_source %></code></pre>
+</div>

data/lib/nexmo/oas/renderer/views/code_snippets/_configure_client.html.erb

@@ -0,0 +1,20 @@
+<div class="Vlt-box Vlt-box--lesspadding Nxd-accordion-emphasis">
+	<h5 class="Vlt-js-accordion__trigger Vlt-accordion__trigger" data-accordion="acc<%= id %>" tabindex="0">
+	        Initialize your dependencies
+	</h5>
+
+	<div id="acc<%=id %>"  class="Vlt-js-accordion__content Vlt-accordion__content Vlt-accordion__content--noborder">
+    <%= create_instructions %>
+    <div class="copy-wrapper">
+
+      <div class="copy-button" data-lang="<%= lang %>" data-block="<%= config['source'] %>" data-section="configure">
+        <%= octicon "clippy", :class => 'top left' %> <span>Copy to Clipboard</span>
+      </div>
+      <pre class="highlight copy-to-clipboard <%= config['title'] %>"><code><%= highlighted_client_source %></code></pre>
+    </div>
+
+    <p><a data-section="configure" data-lang="<%= lang %>" data-block="<%= config['source'] %>" href="<%= client_url %>">View full source</a></p>
+
+  </div>
+</div>
+

data/lib/nexmo/oas/renderer/views/code_snippets/_dependencies.html.erb

@@ -0,0 +1,11 @@
+<div class="Vlt-box Vlt-box--lesspadding Nxd-accordion-emphasis">
+	<h5 class="Vlt-js-accordion__trigger Vlt-accordion__trigger" data-accordion="acc<%= id %>" tabindex="0"><%= title %></h5>
+
+	<div id="acc<%= id %>" class="Vlt-js-accordion__content Vlt-accordion__content Vlt-accordion__content--noborder">
+		    <p><%=deps['text']%></p>
+        <% if deps['code'] %>
+		    <pre class="highlight <%= deps['type'] || 'bash' %> dependencies"><code><%=deps['code']%></code></pre>
+        <% end %>
+	</div>
+</div>
+

data/lib/nexmo/oas/renderer/views/code_snippets/_write_code.html.erb

@@ -0,0 +1,13 @@
+<h2 class="Vlt-title--margin-top3">Write the code</h2>
+<%= add_instructions %>
+
+<div class="copy-wrapper">
+  <div class="copy-button" data-lang="<%= lang %>" data-block="<%= config['source'] %>" data-section="code">
+    <%= octicon "clippy", :class => 'top left' %> <span>Copy to Clipboard</span>
+  </div>
+  <pre class="highlight <%= lexer.tag %> main-code"><code><%= highlighted_code_source %></code></pre>
+
+</div>
+
+<p><a data-section="code" data-lang="<%= lang %>" data-block="<%= config['source'] %>" href="<%= source_url %>">View full source</a></p>
+

data/lib/nexmo/oas/renderer/views/code_snippets/list/plain.html.erb

@@ -0,0 +1,10 @@
+<ul class="Vlt-list Vlt-list--simple">
+  <% @blocks.each do |block| %>
+    <li><a href="<%= block.url %>">
+      <% if block.category %>
+        <%= block.category %> /
+        <% end %>
+      <%= block.title %></a>
+    </li>
+  <% end %>
+</ul>

data/lib/nexmo/oas/renderer/views/concepts/list/plain.html.erb

@@ -0,0 +1,5 @@
+<ul class="Vlt-list Vlt-list--simple">
+  <% @concepts.each do |concept| %>
+    <li><a href="<%= concept.url %>"><%= concept.title %></a><% if concept.description %>: <%= concept.description.render_markdown.gsub(%r{^<p>},'').gsub(%r{^</p>}, '').strip %><% end %></li>
+  <% end %>
+</ul>

data/lib/nexmo/oas/renderer/views/layouts/_head.erb

@@ -0,0 +1,4 @@
+<head>
+  <link rel="stylesheet" href="/assets/stylesheets/volta.min.css"/>
+  <link rel="stylesheet" href="/assets/stylesheets/style.css"/>
+</head>

data/lib/nexmo/oas/renderer/views/layouts/_javascripts.erb

@@ -0,0 +1,9 @@
+<script src="/assets/javascripts/volta.core.js"></script>
+<script src="/assets/javascripts/volta.accordion.js"></script>
+<script src="/assets/javascripts/volta.tabs.js"></script>
+<script src="/assets/javascripts/volta.modal.js"></script>
+<script src="/assets/javascripts/components/format.js"></script>
+<script type="text/javascript">
+  Volta.init(["accordion", "tab", "modal"]);
+  new Format
+</script>

data/lib/nexmo/oas/renderer/views/layouts/api.erb

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html lang="en">
+  <%= erb :'layouts/_head' %>
+
+  <body class="Nxd-template">
+    <nav class="Vlt-sidenav Vlt-sidenav--light" id="Vlt-sidenav">
+      <div class="Vlt-sidenav__scroll">
+        <% begin %>
+          <%= erb :"layouts/#{@specification.side_navigation}" %>
+        <% rescue Errno::ENOENT %>
+          <%= @navigation.navigation_from_content %>
+        <% end %>
+      </div>
+    </nav>
+    <main class="Vlt-main Vlt-main--light Nxd-main" tabindex="2">
+      <div class="Vlt-card" id="primary-content">
+        <%= yield %>
+      </div>
+    </main>
+
+    <%= erb :"layouts/_javascripts" %>
+  </body>
+</html>

data/lib/nexmo/oas/renderer/views/layouts/open_api.erb

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html lang="en">
+  <%= erb :"layouts/_head" %>
+
+  <body class="Nxd-template">
+    <%= yield %>
+
+    <%= erb :"layouts/_javascripts" %>
+  </body>
+</html>

data/lib/nexmo/oas/renderer/views/open_api/_callback.erb

@@ -0,0 +1,5 @@
+<% callback.paths.each do |path| %>
+  <% path.endpoints.each do |endpoint| %>
+    <%= erb :'open_api/_callback_endpoint', locals: { endpoint: endpoint, webhook: webhook } %>
+  <% end %>
+<% end %>

data/lib/nexmo/oas/renderer/views/open_api/_callback_endpoint.erb

@@ -0,0 +1,48 @@
+<div class="Vlt-grid">
+  <div class="Vlt-col Vlt-col--2of3 Nxd-api__docs">
+    <div>
+      <h3 id="<%= endpoint.operationId %>" class="Vlt-title--icon">
+        <%= endpoint.summary %>
+        <% if webhook %>
+          <span class="Vlt-badge Vlt-badge--orange">
+            <i class="icon icon-webhook"></i> Webhook
+          </span>
+        <% else %>
+          <span class="Vlt-badge Vlt-badge--green">
+            <i class="icon icon-callback"></i> Callback
+          </span>
+        <% end %>
+      </h3>
+      <% if endpoint.description %>
+        <p><%= endpoint.description.render_markdown %></p>
+      <% end %>
+
+      <div class="Vlt-badge-combined">
+        <code class="Vlt-badge Vlt-badge--large Nxd-method-badge Nxd-method-badge--<%= endpoint.method %>"><%= endpoint.method.upcase %></code>
+        <code class="Vlt-badge Vlt-badge--large Vlt-badge--grey">
+          <span class="api-path-host">https://example.com</span>
+          <%= (endpoint.raw['x-example-path'] || '/webhooks/event').gsub(/\{(.+?)\}/, '<span class="api-path-parameter">:\1</span>') %>
+        </code>
+      </div>
+
+      <%= erb :'open_api/_parameter_groups', locals: { endpoint: endpoint, callback: true } %>
+    </div>
+  </div>
+
+  <div class="Vlt-col Vlt-col--1of3 Nxd-api__code">
+    <%= erb :'open_api/_code_examples', locals: { endpoint: endpoint } %>
+
+    <h5>Request model</h5>
+
+    <% endpoint.request_body.formats.each_with_index do |format, index| %>
+      <div class="js-format" data-format="<%= format %>">
+        <% schema = endpoint.request_body.schema(format) %>
+        <%= Nexmo::OAS::Renderer::ResponseParserDecorator.new(schema).html(format, xml_options: schema['xml']) %>
+      </div>
+    <% end %>
+  </div>
+</div>
+
+<% endpoint.callbacks.each do |callback| %>
+  <%= erb :'open_api/callback', locals: { callback: callback } %>
+<% end %>

data/lib/nexmo/oas/renderer/views/open_api/_code_examples.erb

@@ -0,0 +1,16 @@
+<%
+  # @todo Re-enable code examples once we decide how to handle them in OAS
+  false && if endpoint.raw['x-code-example-path']
+%>
+  <h5>Example request</h5>
+  <%=
+    markdown = <<~HEREDOC
+    ```tabbed_examples
+    config: #{endpoint.raw['x-code-example-path']}
+    ```
+    HEREDOC
+
+    markdown.render_markdown
+  %>
+<% end %>
+

data/lib/nexmo/oas/renderer/views/open_api/_endpoint.erb

@@ -0,0 +1,156 @@
+<div class="Vlt-grid">
+  <div class="Vlt-col Vlt-col--2of3 Nxd-api__docs">
+    <div>
+      <h3 id='<%= endpoint.operationId %>'><%= endpoint.summary %></h3>
+      <% if endpoint.description %>
+        <p><%= endpoint.description.render_markdown %></p>
+      <% end %>
+
+      <div class="Vlt-badge-combined">
+        <code class="Vlt-badge Vlt-badge--large Nxd-method-badge Nxd-method-badge--<%= endpoint.method %>"><%= endpoint.method.upcase %></code>
+        <code class="Vlt-badge Vlt-badge--large Vlt-badge--grey">
+          <% servers = endpoint.path.servers ? endpoint.path.servers : endpoint.definition.servers %>
+          <span><%= servers[0]['url'] %></span><%= endpoint.path.path.gsub(/\{(.+?)\}/, '<span class="api-path-parameter">:\1</span>') %>
+        </code>
+      </div>
+
+      <% if endpoint.jwt? || endpoint.basic_auth? || endpoint.oauth? %>
+        <h4>Authentication</h4>
+
+        <% if endpoint.jwt? && endpoint.basic_auth? %>
+          <p>This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.</p>
+
+          <p>You can use <em>either</em> JWT or Basic authentication, but not both at the same time.</p>
+        <% end %>
+
+        <div class="Vlt-table Vlt-table--data Vlt-table--bordered">
+          <table>
+            <thead>
+              <tr>
+                <th>Key</th>
+                <th>Description</th>
+                <th>Example</th>
+                <th>Default</th>
+              </tr>
+            </thead>
+            <tbody>
+              <% if endpoint.oauth? %>
+                <tr>
+                  <td>
+                    <b>Authorization</b>
+                  </td>
+                  <td>
+                    <b>Your OAuth token.</b><br>
+                    <small><a href="/vonage-business-cloud/vbc-apis/getting-started/authentication">Read more about OAuth tokens</a></small>
+                  </td>
+                  <td><code>Bearer &lt;access_token&gt;</code></td>
+                  <td>
+                    <em>None</em>
+                  </td>
+                </tr>
+              <% end %>
+
+              <% if endpoint.jwt? %>
+                <tr>
+                  <td>
+                    <b>Authorization</b>
+                  </td>
+                  <td>
+                    <b>Your JSON web token.</b><br>
+                    <small><a href="/concepts/guides/authentication#json-web-tokens-jwt">Read more about JWTs</a></small>
+                  </td>
+                  <td><code>Bearer &lt;JWT&gt;</code></td>
+                  <td>
+                    <em>None</em>
+                  </td>
+                </tr>
+              <% end %>
+
+              <% if endpoint.basic_auth? %>
+                <tr>
+                  <td>
+                    <b>Authorization</b>
+                  </td>
+                  <td>
+                    <b>Base64 encoded API key and secret joined by a colon.</b><br>
+                    <small><a href="/concepts/guides/authentication#header-based-api-key-and-secret-authentication">Read more</a></small>
+                  </td>
+                  <td><code>Basic &lt;base64&gt;</code></td>
+                  <td>
+                    <i>None</i>
+                  </td>
+                </tr>
+              <% end %>
+            </tbody>
+          </table>
+        </div>
+      <% end %>
+
+      <%= erb :'open_api/_parameter_groups', locals: { endpoint: endpoint } %>
+      <%= erb :'open_api/_response_descriptions', locals: { endpoint: endpoint, anchor_prefix: "response-#{endpoint.operationId}", auto_expand_responses: @auto_expand_responses } %>
+
+    </div>
+  </div>
+
+  <div class="Vlt-col Vlt-col--1of3 Nxd-api__code">
+    <%= erb :'open_api/_code_examples', locals: { endpoint: endpoint } %>
+
+    <% endpoint.responses.each do |response| %>
+      <%
+        id = SecureRandom.hex
+        expand_response = response.code[0] == '2' && response.raw['x-expand-response'] != false
+        expand_response = true if response.raw['x-expand-response']
+      %>
+
+      <div class="Vlt-accordion">
+        <button tabindex="0" class="Vlt-accordion__trigger <%= expand_response ? 'Vlt-accordion__trigger_active' : '' %>">
+          <h5 class="Vlt-title--nomargin">HTTP response
+            <span class="Vlt-badge Vlt-badge--<%= response.code[0] == '2' ? 'green' : response.code[0] == '3' ? 'yellow' : 'red'  %>"><%= response.code %></span>
+          </h5>
+        </button>
+
+        <div class="Vlt-accordion__content <%= expand_response ? 'Vlt-accordion__content_open' : '' %>">
+          <% response.formats.each_with_index do |format, index| %>
+            <div class="js-format" data-format="<%= format %>">
+              <% if response.exhibits_one_of_multiple_schemas?(format) %>
+                <%
+                  schema_tab_ids = []
+                  id = SecureRandom.hex
+                  response.split_schemas(format).each { schema_tab_ids << SecureRandom.hex }
+                %>
+
+                <div class="Vlt-tabs">
+                  <div class="Vlt-tabs__header">
+                    <% response.split_schemas(format).each_with_index do |schema, index| %>
+                      <div tabindex="<%= schema_tab_ids[index] %>" <% if index.zero? %>class="Vlt-tabs__link Vlt-tabs__link_active" aria-selected="true"<% else %>class="Vlt-tabs__link"<% end %>>
+                        <%= schema['description'] || "Response #{index + 1}" %>
+                      </div>
+                    <% end %>
+                  </div>
+                  <div class="Vlt-tabs__content">
+                    <% response.split_schemas(format).each_with_index do |schema, index| %>
+                      <div class="Vlt-tabs__panel <% if index.zero? %>Vlt-tabs__panel_active<% end %>">
+                        <%= Nexmo::OAS::Renderer::ResponseParserDecorator.new(schema).html(format, xml_options: schema['xml']) %>
+                      </div>
+                    <% end %>
+                  </div>
+                </div>
+              <% else %>
+                <% schema = response.schema(format) %>
+                <%= Nexmo::OAS::Renderer::ResponseParserDecorator.new(schema).html(format, xml_options: schema['xml']) %>
+              <% end %>
+            </div>
+          <% end %>
+        </div>
+
+        <% if response.code == '204' || response.formats.empty? %>
+          <pre class="highlight"><code>No content</code></pre>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+</div>
+
+<% endpoint.callbacks.each do |callback| %>
+  <%= erb :'open_api/_callback', locals: { callback: callback, webhook: false } %>
+<% end %>