nexmo-oas-renderer 2.1.1

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

@@ -0,0 +1,56 @@
+<% callback = false if callback.nil? %>
+
+<% if endpoint.parameters.select { |p| p.in == 'header'}.any? %>
+  <h4>Header Parameters</h4>
+  <%= erb :'open_api/_parameters', locals: { parameters: endpoint.parameters.select { |p| p.in == 'header' }, callback: callback } %>
+<% end %>
+
+<% if endpoint.path_parameters.any? %>
+  <h4>Path Parameters</h4>
+  <%= erb :'open_api/_parameters', locals: { parameters: endpoint.path_parameters, callback: callback } %>
+<% end %>
+
+<% if endpoint.query_parameters.any? %>
+  <h4>Query Parameter</h4>
+  <%= erb :'open_api/_parameters', locals: { parameters: endpoint.query_parameters, callback: callback } %>
+<% end %>
+
+<% if endpoint.request_body %>
+  <% format = endpoint.request_body.formats[0] %>
+  <h4>
+    Request body
+    <span class="Vlt-badge Vlt-badge--blue"><%= format %></span>
+  </h4>
+
+  <% if endpoint.request_body.description %>
+    <%= endpoint.request_body.description.render_markdown %>
+  <% end %>
+
+  <% unless endpoint.request_body.exhibits_one_of_multiple_schemas?(format) %>
+
+    <%
+      # @mheap: This is hacky handling for allOf, but it works for now
+      # We probably want real allOf support in OasParser, but that's more time than I have right now
+      allOf = endpoint.request_body.content[format]['schema']['allOf']
+      if allOf
+        params = endpoint.request_body.handle_all_of(allOf)
+      else
+        params = endpoint.request_body.properties_for_format(format)
+      end
+      if params
+    %>
+
+      <%= erb :'open_api/_parameters', locals: { endpoint:endpoint, parameters: params, callback: callback } %>
+    <% end %>
+  <% else %>
+
+    <%
+      # This can likely be better done as a presenter, but it works for now
+      schema = endpoint.request_body.content[format]['schema']['oneOf']
+      %>
+      <%= erb :'open_api/_tabbed_parameters', locals: { body: endpoint.request_body, schema: schema, format: format, callback: callback } %>
+    <%
+    end
+  end
+%>
+

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

@@ -0,0 +1,115 @@
+<%
+  model = false if model.nil?
+  callback = false if callback.nil?
+  format = nil if format.nil?
+
+  unless defined?(parent)
+    parent = ""
+  else
+    parent = "#{parent}."
+  end
+
+  isOneOf = false unless defined?(isOneOf)
+%>
+
+<% parameters.each do |parameter| %>
+
+  <div class="oas-grid">
+    <div class="oas-parameter-name <%= !parent.blank? ? 'oas-parameter-name-nested' : '' %>">
+      <% if parent.blank? %>
+          <b><%= parameter.name %></b>
+      <% else %>
+        <div class="Vlt-tooltip Vlt-tooltip--top" title="<%= parent %><%= parameter.name %>">
+          <b><%= parameter.name %></b>
+        </div>
+      <% end %>
+
+      <% if @specification.formats.any? %>
+        <% if @specification.formats.include?('text/xml') %>
+          <span class="js-format" data-format="text/xml">
+            <% if parameter.is_xml_attribute? %>
+              | <span class="xml-flag">Attribute</span>
+            <% end %>
+
+            <% if parameter.is_xml_text? %>
+              | <span class="xml-flag">Value</span>
+            <% end %>
+          </span>
+        <% end %>
+      <% end %>
+    </div>
+    <div class="oas-parameter-description">
+
+      <div class="oas-parameter-meta">
+        <em>
+          <%= parameter.type %>
+          <% if parameter.format %>
+            (<%= parameter.format %>)
+          <% end %>
+
+          <% if parameter.array? %>
+            <% if parameter.items && parameter.items['type'] %>
+              of <%= (parameter.items['type']) %>s
+            <% end %>
+          <% end %>
+        </em>
+
+        <% if parameter.required and parameter.type %>|<% end %>
+        <% if parameter.required %>
+          <span class="constraint">Required</span>
+        <% end %>
+
+        <% if parameter.minimum || parameter.raw['minLength'] %>
+          | <span class="constraint">Min:</span> <%= parameter.minimum || parameter.raw['minLength'] %>
+        <% end %>
+        <% if parameter.maximum || parameter.raw['maxLength'] %>
+          | <span class="constraint">Max:</span> <%= parameter.maximum || parameter.raw['maxLength'] %>
+        <% end %>
+      </div>
+
+      <%= (parameter.description || parameter.schema['description'] || '').render_markdown %>
+
+      <% if parameter.enum %>
+        <small class="Vlt-grey-dark">
+          <%= (callback || model) ? "One of:" : "Must be one of:" %>
+          <%= parameter_values(parameter.enum) %>
+        </small>
+      <% end %>
+
+
+  </div>
+
+    <% if parameter.array? &&  parameter.items && parameter.items['oneOf'] %>
+
+      <%
+        # Handle specific case - an array that contains a oneOf
+        params = parameter.items['oneOf'].map do |p|
+          p['format'] = parameter.format
+          OasParser::Parameter.new(self, p)
+        end
+
+      %>
+      <div class="oas-parameter-nested">
+        <%= erb :'open_api/_tabbed_single_parameter', locals: { parent: "#{parameter.name}[]", parameters: params, format: format, callback: callback } %>
+      </div>
+
+    <% end %>
+
+    <% if parameter.array? && parameter.items && !parameter.items['oneOf'] %>
+      <%
+        # mheap: We only want to recurse if there are example properties in the array definition
+        if parameter.items['type'] && parameter.items['type'] == 'object' && parameter.items['properties']
+      %>
+        <div class="oas-parameter-nested">
+          <%= erb :'open_api/_parameters', locals: { parent: "#{parent}#{parameter.name}[]", parameters: parameter.properties, model: model, format: format, callback: callback } %>
+        </div>
+      <% end %>
+    <% end  %>
+    <% if parameter.properties && parameter.object? && parameter.properties.size.positive? %>
+      <div class="oas-parameter-nested">
+        <%= erb :'open_api/_parameters', locals: { parent: "#{parent}#{parameter.name}", parameters: parameter.properties, model: model, format: format, callback: callback } %>
+      </div>
+    <% end %>
+  </div>
+<% end %>
+

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

@@ -0,0 +1,4 @@
+<% output = Nexmo::OAS::Renderer::Presenters::RequestBodyRaw.new(parameters) %>
+
+<h4>Example Request</h4>
+<pre class="highlight javascript" style="white-space: pre-wrap"><code><%= output.to_json %></code></pre>

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

@@ -0,0 +1,70 @@
+<%
+  body = endpoint.request_body
+
+  # If we're calling this recursively (a oneOf a oneOf) then schema is passed in
+  # rather than pulling it from the body
+  schema ||= endpoint.request_body.content[format]['schema']['oneOf']
+
+  # Handle any cases where the top level of the oneOf is an allOf
+  schemas = schema.map do |s|
+    if s['allOf']
+      newSchema = body.handle_all_of(s)
+      s.each do |k,v|
+        newSchema[k] = v
+      end
+
+      next newSchema
+    end
+    s
+  end
+
+  panels = []
+
+  schemas.each_with_index do |schema, index|
+    if schema['properties']
+      schema['properties'] = schema['properties'].map do |name, definition|
+        # Sometimes we get in to a weird situation where we already have a Property
+        next name if name.instance_of?(OasParser::Property)
+        OasParser::Property.new(self, schema, name, definition)
+      end
+      .sort_by do |prop|
+        prop.required ? -1 : 1
+      end
+    end
+
+    subtitle = schema['title'] || schema['description']
+
+    if defined?(parent)
+      subtitle = "#{parent} &raquo; #{subtitle}"
+    end
+
+    panels.push({
+      'title' => subtitle,
+      'description' => schema['title'] || schema['description'],
+      'parameters' => schema['properties'],
+      'oneOf' => schema['oneOf'],
+      'x-tab-id' => schema['x-tab-id'] || schema['title'].parameterize,
+      'active' => index == 0
+    })
+  end
+%>
+
+<div class="Vlt-tabs js-format" data-format="<%= format %>">
+  <div class="Vlt-tabs__header" style="display:none;" role="tablist" aria-label="Responses">
+    <% panels.each do |panel| %>
+      <span data-tab-link="<%= panel['x-tab-id'] %>" class="Vlt-tabs__link <%= panel['active'] ? 'Vlt-tabs__link_active' : '' %>">
+      </span>
+    <% end %>
+  </div>
+  <div class="Vlt-tabs__content">
+    <% panels.each do |panel| %>
+      <div class="Vlt-tabs__panel <%= panel['active'] ? 'Vlt-tabs__panel_active' : '' %>">
+        <% unless panel['oneOf'] %>
+          <%= erb :'open_api/_request_single', locals: { title: title, subtitle: panel['title'], endpoint: endpoint, params: panel['parameters'], format: format } %>
+        <% else %>
+          <%= erb :'open_api/_request_one_of', locals: { title: title, parent: panel['title'], endpoint: endpoint, schema: panel['oneOf'], format: format } %>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+</div>

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

@@ -0,0 +1,53 @@
+<%
+  renderer = Nexmo::OAS::Renderer::Presenters::RequestBodyRaw
+  params ||= endpoint.request_body.properties_for_format(format)
+
+  requests = []
+
+  # Only show the required fields tab if there are any required fields
+  required_params = params.select do |param|
+    param.required
+  end
+
+  requests.push(
+      {
+          'title' => 'Required Fields Only',
+          'id' => 'required-only',
+          'value' => renderer.new(params, { 'required_only' => true }, endpoint)
+      }) if required_params.any?
+
+  # Always show the all fields tab
+  requests.push(
+      {
+          'title' => 'All Fields',
+          'id' => 'all-fields',
+          'value' => renderer.new(params, { 'required_only' => false }, endpoint)
+      }
+  )
+
+  # Remove the "required only" option if the two request bodies are identical
+  unique_requests = requests.map { |r| r['value'].to_format('application/json') }.to_set.size
+  requests.shift if (unique_requests == 1 && requests.size != unique_requests)
+
+  title = "Example Request" unless title
+  if defined?(subtitle)
+    title = "#{title} &raquo; #{subtitle}"
+  end
+
+%>
+
+<h4 class="Vlt-grey-light"><%= title %></h4>
+  <div class="Vlt-tabs">
+    <div class="Vlt-tabs__header" role="tablist" aria-label="Responses">
+      <% requests.each_with_index do |request, index| %>
+        <div role='tab' tabindex="-1" data-tab-link="<%= request['id'] %>" class="<%= index === 0 ? 'Vlt-tabs__link_active' : '' %> Vlt-tabs__link tab-sync"><%= request['title'] %></div>
+        <% end %>
+    </div>
+    <div class="Vlt-tabs__content">
+      <% requests.each_with_index do |request, index| %>
+        <div role='tabpanel' class="Vlt-js-tabs__panel <%= index === 0 ? 'Vlt-tabs__panel_active' : '' %>">
+          <pre class="<%= format == 'application/json' ? 'language-json' : 'language-shell' %> Vlt-prism--copy-disabled <%= @theme_light ? 'Vlt-prism--dark' : '' %>"><code><%= request['value'].to_format(format) %></code></pre>
+        </div>
+      <% end %>
+    </div>
+</div>

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

@@ -0,0 +1,22 @@
+<%
+  return unless endpoint.request_body
+  return if endpoint.request_body.raw['x-hide-request']
+  title = defined?(title) ? title : nil
+
+  renderer = Nexmo::OAS::Renderer::Presenters::RequestBodyRaw
+
+  # The first format defined is preferred. This is usually application/json
+  format = endpoint.request_body.formats[0]
+%>
+
+<%
+  if endpoint.request_body.exhibits_one_of_multiple_schemas?(format)
+%>
+  <%= erb :'open_api/_request_one_of', locals: { endpoint: endpoint, format: format, title: title } %>
+
+<% else %>
+  <%= erb :'open_api/_request_single', locals: { endpoint: endpoint, format: format, title: title} %>
+<%
+  end
+%>
+

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

@@ -0,0 +1,130 @@
+<%
+  # @mheap: This is hacky handling for allOf, but it works for now
+  allOf = schema['allOf']
+  if allOf
+    schema = allOf.reduce { |a,b| a.deep_merge(b) }
+  end
+%>
+
+<%
+  # If it's an array, look at the items for the response schema as all items within
+  # the array are expected to be identical
+  schema = schema['items'] if schema['type'] == 'array'
+%>
+
+<% if schema['properties'] %>
+  <% parentField = parentField ? "#{parentField}." : '' %>
+  <% schema['properties'].each do |key, parameter| %>
+    <%
+      next if key == '_links'
+      next if parameter['x-skip-response-description']
+      parent = "#{endpoint.method}_#{endpoint.path.path.gsub("/", "_")[1..-1]}" unless parent
+      responseFieldId = parent + "_" + key
+    %>
+    <div class="oas-grid">
+      <div id="<%= responseFieldId %>" class="oas-parameter-name <%= !parentField.blank? ? 'oas-parameter-name-nested' : '' %>">
+        <% if parentField.blank? %>
+          <b><%= key %></b>
+        <% else %>
+          <div class="Vlt-tooltip Vlt-tooltip--top" title="<%= parentField %><%= key %>">
+            <b><%= key %></b>
+          </div>
+        <% end %>
+      </div>
+
+      <div class="oas-parameter-description">
+        <div class="oas-parameter-meta">
+          <%= parameter['type'] %>
+          <% if parameter['type'] == 'array' %>
+            <% if parameter['items'] && parameter['items']['type'] %>
+              of <%= (parameter['items']['type']) %>s
+            <% end %>
+          <% end %>
+        </div>
+
+        <%= (parameter['description'] || '' ).render_markdown %>
+
+        <% if parameter['enum'] %>
+          <small class="Vlt-grey-dark">
+            One of:
+            <%= parameter_values(parameter['enum']) %>
+          </small>
+        <% end %>
+
+      </div>
+
+
+      <% arrayMarker = "" %>
+      <% if parameter['items'] # If this is an array, we need to show the structure of the children %>
+        <% arrayMarker = "[]" %>
+        <% if parameter['items']['oneOf'] || parameter['items']['anyOf'] # If it's a oneOf/anyOf, we need tabs! %>
+          <%
+
+            if parameter['items']['oneOf']
+              qualifier = 'one'
+              lookupKey = 'oneOf'
+            else
+              qualifier = 'any'
+              lookupKey = 'anyOf'
+            end
+
+            schemas = parameter['items'][lookupKey].map do |item|
+              if item['allOf']
+                item = item.deep_merge(item['allOf'].reduce { |a,b| a.deep_merge(b) })
+                item.delete('allOf')
+              end
+              item
+            end
+          %>
+        <% else %>
+          <% parameter['properties'] = parameter['items']['properties'] %>
+        <% end %>
+      <% end %>
+
+      <%
+        schemas = [parameter]
+      %>
+
+      <% if schemas %>
+        <% needs_tabs = schemas.size > 1 %>
+            <% if needs_tabs %>
+              <div class="Vlt-callout Vlt-callout--shoutout">
+                <i></i>
+                <div class="Vlt-callout__content">
+                  This array contains <strong><%= qualifier %></strong> of the following objects:
+                </div>
+              </div>
+              <div class="Vlt-tabs js-format">
+                <div class="Vlt-tabs__header Vlt-tabs__header--bordered" role="tablist" aria-label="Responses">
+                  <% schemas.each_with_index do |schema, index| %>
+                    <div
+                      class="Vlt-tabs__link <%= index == 0 ? 'Vlt-tabs__link_active' : '' %> <%= schema['x-tab-id'] ? "tab-sync" : '' %>"
+                      <% if schema['x-tab-id'] %>
+                      data-tab-link="<%= schema['x-tab-id'] %>"
+                      <% end %>
+                      >
+                      <%= schema['description'] %>
+                    </div>
+                  <% end %>
+                </div>
+                <div class="Vlt-tabs__content">
+            <% end %>
+
+            <% schemas.each_with_index do |value, index| %>
+              <div class="Vlt-tabs__panel <%= index == 0 ? 'Vlt-tabs__panel_active' : '' %>">
+                <div class="oas-parameter-nested">
+                <%= erb :'open_api/_response_description_parameters', locals: { endpoint: endpoint, schema: value, parent: responseFieldId, parentField: "#{parentField}#{key}#{arrayMarker}" } %>
+                </div>
+              </div>
+            <% end %>
+
+            <% if needs_tabs %>
+              </div>
+              </div>
+            <% end %>
+      <% end %>
+    </div>
+  <% end %>
+<% end %>
+
+