nexmo-oas-renderer 0.11.3 → 2.1.2

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

@@ -0,0 +1,71 @@
+<div class="Vlt-grid">
+  <div class="Vlt-col oas-left-panel header-row" style="padding-top:20px;">
+    <a href="<%= @theme_link %>" class="Vlt-switch Vlt-switch--secondary" style="float:right;">
+        <span class="Vlt-switch__slider"></span>
+    </a>
+
+
+    <div class="Nxd-api__title">
+      <h1>
+        <%= definition.info['title'] %>
+      </h1>
+      <% if definition.info['x-label'] %>
+        <div>
+                <span class="Vlt-badge Vlt-badge--<%= definition.info['x-label'].parameterize %>">
+                  <%= definition.info['x-label'] %>
+                </span>
+        </div>
+      <% end %>
+    </div>
+
+    <% if definition.info['description'] %>
+      <p><%= definition.info['description'].render_markdown %></p>
+    <% end %>
+
+    <div class="Vlt-grid">
+      <div class="Vlt-col">
+        <a href=<%= url("#{request.path}.#{definition.format}") %> class='Vlt-btn Vlt-btn--secondary Vlt-btn--app'>
+        <svg><use xlink:href="/assets/symbol/volta-icons.svg#Vlt-icon-download" /></svg>
+        Download OAS 3 Definition
+        </a>
+      </div>
+      <div class="Vlt-col Vlt-right Vlt-right-sm">
+        <a href="<%=  Nexmo::OAS::Renderer::API.github_path %>/<%= @specification.definition_name %>.yml" class='Vlt-btn Vlt-btn--tertiary Vlt-btn--app Vlt-right Vlt-bg-grey-lighter'>
+          <svg className="Vlt-icon Vlt-black">
+            <use xlink:href="/assets/symbol/volta-icons.svg#Vlt-icon-github" />
+          </svg>
+          Improve this specification
+        </a>
+      </div>
+    </div>
+
+    <%
+      # If there's only one group, everything is untagged
+      if @specification.groups.size === 1
+    %>
+      <%= erb :'open_api/_available_endpoints', locals: { endpoints: definition.endpoints } %>
+    <% end %>
+
+  </div>
+
+  <%
+    has_switcher = @specification.available_versions && @specification.available_versions.count > 1
+  %>
+
+  <div class="oas-right-panel Vlt-col <%= has_switcher ? '' : 'sm-hidden' %>">
+
+    <% if has_switcher %>
+      <div class="Vlt-callout Vlt-callout--shoutout Nxd-version">
+        <i></i>
+        <div class="Vlt-callout__content">
+          <h4>There are multiple versions of this API available</h4>
+          <p>
+            <% @specification.available_versions.each do |v| %>
+              <a href="/api/<%= v['name'] %>" <%= v['version'] == @specification.current_version ? 'class=active':'' %>>Version <%= v['version'] %></a> <%= '|' unless v == @specification.available_versions.last %>
+            <% end %>
+          </p>
+        </div>
+      </div>
+    <% end %>
+  </div>
+</div>

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

@@ -1,31 +1,35 @@
-<div class="Vlt-grid <% if !group['schema'] %> Nxd-api--noborder Vlt-article--reverse<% end %>">
-  <div class="Vlt-col Vlt-col--2of3 Nxd-api__docs">
-    <div>
-      <h2 id="<%= group['name'].parameterize %>" class='Vlt-grey-dark'><%= group['name'] %></h2>
-      <p class: "Vlt-grey-darker"><%= group['description']&.render_markdown %></p>
-
-      <% if group['schema'] %>
-        <% group['schema'].each do |format, schema| %>
-          <div class="js-format" data-format="<%= format %>">
-            <%
-              if schema['properties']
-                properties = schema['properties']
-              elsif schema['allOf']
-                properties = schema['allOf'].map { |o| o['properties'] }.reduce(&:merge)
-              end
-
-              properties = properties.map do |name, definition|
-                OasParser::Property.new(self, schema, name, definition)
-              end
-            %>
-
-            <%= erb :'open_api/_parameters', locals: { parameters: properties, model: true, format: format  } %>
-          </div>
-        <% end %>
+<div class="Vlt-grid">
+  <div class="Vlt-col oas-left-panel">
+
+    <h2 id="<%= group['name'].parameterize %>" class='Vlt-grey-dark group-header'><%= group['name'] %></h2>
+    <p class="Vlt-grey-darker"><%= group['description']&.render_markdown %></p>
+
+
+    <%= erb :'open_api/_available_endpoints', locals: { endpoints: endpoints } %>
+
+    <% if group['schema'] %>
+      <% group['schema'].each do |format, schema| %>
+        <div class="js-format" data-format="<%= format %>">
+          <%
+            if schema['properties']
+              properties = schema['properties']
+            elsif schema['allOf']
+              properties = schema['allOf'].map { |o| o['properties'] }.reduce(&:merge)
+            end
+
+            properties = properties.map do |name, definition|
+              OasParser::Property.new(self, schema, name, definition)
+            end
+          %>
+
+          <%= erb :'open_api/_parameters', locals: { parameters: properties, model: true, format: format  } %>
+        </div>
       <% end %>
-    </div>
+    <% end %>
   </div>
-  <div class="Vlt-col Vlt-col--1of3 Nxd-api__code">
+
+  <div class="Vlt-col oas-right-panel <%= !group['schema'] ? 'sm-hidden' : '' %>">
+
     <% if group['schema'] %>
       <% group['schema'].each do |format, schema| %>
         <div class="js-format" data-format="<%= format %>">
@@ -34,5 +38,6 @@
         </div>
       <% end %>
     <% end %>
+
   </div>
 </div>

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

@@ -1,92 +1,68 @@
-<div id="Vlt-sidenav" class="Vlt-sidenav">
-  <div class="Vlt-sidenav__scroll">
-    <ul class="Vlt-sidemenu Vlt-sidemenu--rounded navigation--documentation">
-      <li>
-        <h5 class="Vlt-sidemenu__title Vlt-sidemenu__title--border"><%= definition.info['title'] %></h5>
-      </li>
-      <li>
-        <a class="Vlt-sidemenu__link" href="#overview">Overview</a>
-      </li>
+<header class="oas-navbar oas-navbar-full">
+  <% if @specification.groups.size == 1 %>
+    <a href="#top" class="Vlt-btn Vlt-btn--tertiary group-link">Available Operations</a>
+  <% end %>
 
-      <% @specification.groups.each do |name, endpoints| %>
-        <% if name %>
-          <%
-            group = definition.raw['tags'].select { |tag| tag['name'].capitalize == name.capitalize }.first
-            raise "Could not find 'tags' entry for #{name.capitalize}" unless group
-           %>
-          <li>
-            <h5 class="Vlt-sidemenu__title Vlt-sidemenu__title--border"><%= group['name'] %></h5>
-          </li>
-        <% end %>
 
-        <% endpoints.each do |endpoint| %>
-          <% raise "Missing `operationId` on #{endpoint.path.path} path" unless endpoint.operationId %>
-          <li>
-            <a href="#<%= endpoint.operationId %>" class="Vlt-sidemenu__link">
-              <svg class="Vlt-grey-darker"><use xlink:href="/assets/symbol/volta-icons.svg#Vlt-icon-code" /></svg>
+  <% @specification.groups.each do |name, endpoints| %>
+    <% next unless name %>
+    <a href="#<%= name.parameterize %>" class="Vlt-btn Vlt-btn--tertiary group-link"><%= name %></a>
+  <% end %>
 
-              <span class="Vlt-sidemenu__label">
-                <%= normalize_summary_title(endpoint.summary, endpoint.operationId) %>
-              </span>
-              <span class="Vlt-badge Vlt-badge--margin-left Nxd-method-badge Nxd-method-badge--<%= endpoint.method %> Vlt-white Vlt-badge--small"><%= endpoint.method %></span>
-            </a>
-          </li>
+  <% if @specification.definition.raw['x-webhooks'] || definition.webhooks.size.positive? %>
+    <a href="#webhooks" class="Vlt-btn Vlt-btn--tertiary group-link">Webhooks</a>
+  <% end %>
 
-          <% if endpoint.callbacks.any? %>
-            <% endpoint.callbacks.each do |callback| %>
-              <% callback.paths.each do |path| %>
-                <% path.endpoints.each do |endpoint| %>
-                  <li class="Nxd-menu__indent">
-                    <a href="#<%= endpoint.operationId %>" class="Vlt-sidemenu__link">
-                      <svg class="Vlt-grey-darker"><use xlink:href="/assets/symbol/volta-icons.svg#Vlt-icon-toggle" /></svg>
-                      <span class="Vlt-sidemenu__label"><%= endpoint.summary %></span>
-                    </a>
-                  </li>
-                <% end %>
-              <% end %>
-            <% end %>
-          <% end %>
-        <% end %>
 
-        <% definition.webhooks.each do |webhook| %>
-          <% webhook.endpoints.each do |endpoint| %>
-            <li>
-              <a href="#<%= webhook.name %>" class="Vlt-sidemenu__link">
-                <svg class="Vlt-grey-darker"><use xlink:href="/assets/symbol/volta-icons.svg#Vlt-icon-mind-map" /></svg>
-                <span class="Vlt-sidemenu__label"><%= endpoint.summary %></span>
-              </a>
-            </li>
-          <% end %>
+  <% if @specification.formats.size > 1 %>
+    <div class="Vlt-native-dropdown">
+      <select class="js-format-selector">
+        <% @specification.formats.each do |value, name| %>
+          <option value="<%= value %>"><%= name %> Responses</option>
         <% end %>
+      </select>
+    </div>
+  <% end %>
+</header>
 
-        <% if definition.raw['x-webhooks'] %>
-          <% definition.raw['x-webhooks'].each do |name, definition| %>
-            <% callback = OasParser::Callback.new(self, name, definition) %>
-
-            <% callback.paths.each do |path| %>
-              <% path.endpoints.each do |endpoint| %>
-                <li>
-                  <a href="#<%= name %>" class="Vlt-sidemenu__link">
-                    <svg class="Vlt-grey-darker"><use xlink:href="/assets/symbol/volta-icons.svg#Vlt-icon-mind-map" /></svg>
-                    <span class="Vlt-sidemenu__label"><%= endpoint.summary %></span>
-                  </a>
-                </li>
-              <% end %>
+<header class="oas-navbar oas-navbar-small">
+  <div id="oas-nav-accordion" style="width: 100%;">
+    <span role="link" class="oas-trigger">
+      <% if @specification.formats.size > 1 %>
+        <div class="Vlt-native-dropdown">
+          <select class="js-format-selector">
+            <% @specification.formats.each do |value, name| %>
+              <option value="<%= value %>"><%= name %> Responses</option>
             <% end %>
-          <% end %>
-        <% end %>
+          </select>
+        </div>
+      <% end %>
+    </span>
 
-        <% if name %>
-          </li>
+    <div class="oas-trigger-content">
+      <% if @specification.groups.size == 1 %>
+      <a href="#top" class="Vlt-btn Vlt-btn--tertiary group-link">Available Operations</a>
+      <% end %>
+
+      <br />
+      <br />
+
+      <% has_webhooks = @specification.definition.raw['x-webhooks'] || definition.webhooks.size.positive? %>
+      <% if @specification.groups.size > 1 || has_webhooks %>
+        <h4>Endpoints</h4>
+
+        <% @specification.groups.each do |name, endpoints| %>
+          <% next unless name %>
+          <a href="#<%= name.parameterize %>" class="Vlt-btn Vlt-btn--tertiary group-link"><%= name %></a>
         <% end %>
       <% end %>
 
-      <% if @specification.definition_errors %>
-        <li>
-          <a class="Vlt-sidemenu__link" href="#errors">Errors</a>
-        </li>
+      <% if has_webhooks %>
+        <a href="#webhooks" class="Vlt-btn Vlt-btn--tertiary group-link">Webhooks</a>
       <% end %>
-      </li>
-    </ul>
+
+    </div>
   </div>
-</div>
+</header>
+
+<span id="top"></span>

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

@@ -33,17 +33,14 @@
       # 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 = allOf.reduce { |a,b| a.deep_merge(b) }
-        params = params['properties'].map do |name, definition|
-          OasParser::Property.new(nil, params, name, definition)
-        end
+        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: { parameters: params, callback: callback } %>
+      <%= erb :'open_api/_parameters', locals: { endpoint:endpoint, parameters: params, callback: callback } %>
     <% end %>
   <% else %>
 

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

@@ -2,185 +2,114 @@
   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)
 %>
 
-<div class="Vlt-table Vlt-section Vlt-table--bordered">
-  <table>
-    <thead>
-      <tr>
-        <th>Key</th>
-        <th>Description</th>
-        <% unless model %>
-          <th>Example</th>
-          <% unless callback %>
-            <th>Default</th>
-          <% end %>
-        <% end %>
-      </tr>
-    </thead>
-    <tbody>
-      <% parameters.each do |parameter| %>
-      <% next if parameter.name == "_links" %>
-        <tr class="<% if parameter.collection? %> Vlt-table__row--noline <% end %>">
-          <td class="Vlt-table__cell--nowrap">
-            <b><%= parameter.name %></b><br>
-            <small>
-              <% if parameter.required %>
-                <span class="flag flag--strong">Required</span>
-              <% 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="flag">Attribute</span>
-                    <% end %>
-
-                    <% if parameter.is_xml_text? %>
-                      | <span class="flag">Value</span>
-                    <% end %>
-                  </span>
-                <% end %>
-              <% end %>
-
-              <i>
-                <% if parameter.required and parameter.type %>|<% end %> <%= parameter.type %>
-                <% if parameter.format %>
-                  | (<%= parameter.format %>)
-                <% end %>
-                <% if parameter.array? %>
-                  <br>
-                  <% if parameter.items && parameter.items['type'] %>
-                    of <%= (parameter.items['type']) %>s
-                  <% end %>
-                <% end %>
-              </i>
-            </small>
-          </td>
-
-        <%
-          # If it's a oneOf we show a list rather than description/example/default
-          if parameter.oneOf?
-        %>
-          <td colspan="3">
-            <h4>Any one of the following:</h4>
-            <% parameter.properties.each do |property| %>
-              <h5><%= property['description'] %></h5>
-              <%= erb :'open_api/_parameters', locals: { parameters: property['properties'], model: model, format: format, callback: callback } %>
-            <% end %>
-          </td>
-        <%
-          # Otherwise we show the remaining 3 columns
-          else
-        %>
-          <td>
-            <% if parameter.collection? || parameter.oneOf? %>
-              <% if parameter.raw['x-nexmo-developer-collection-description-shown'] %>
-                <%= (parameter.description || parameter.schema['description'] || '<i>None</i>').render_markdown %>
-              <% end %>
-            <% else %>
-              <%= (parameter.description || parameter.schema['description'] || '<i>None</i>').render_markdown %>
-            <% end %>
+<% parameters.each do |parameter| %>
 
-            <% if parameter.enum %>
-              <br>
-              <small class="Vlt-grey-dark">
-                <%= (callback || model) ? "One of:" : "Must be one of:" %>
-                <%= parameter_values(parameter.enum) %>
-              </small>
-            <% end %>
+  <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 parameter.raw['x-possible-values'] %>
-              <br>
-              <small class="Vlt-grey-dark">
-                Will be one of:
-                <%= parameter_values(parameter.raw['x-possible-values']) %>
-              </small>
+      <% 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.minimum || parameter.maximum %>
-              <br>
-              <small class="Vlt-grey-dark">
-                <% if parameter.minimum && parameter.maximum %>
-                  Must be between <%= "<code>#{parameter.minimum}</code>"%> and <%= "<code>#{parameter.maximum}</code>"%>
-                <% elsif parameter.minimum %>
-                  Must be at least <%= "<code>#{parameter.minimum}</code>"%>
-                <% else %>
-                  Must be at most <%= "<code>#{parameter.maximum}</code>"%>
-                <% end %>
-              </small>
-            <% end %>
-          </td>
-
-          <% unless model %>
-            <% if parameter.collection? || parameter.oneOf? %>
-              <% if parameter.raw['x-nexmo-developer-collection-description-shown'] %>
-                <td>
-                  <%= (parameter.example ? "<code><pre>#{parameter.example}</pre></code>" : '')%>
-                </td>
-              <% end %>
-            <% else %>
-              <td>
-                <%= (parameter.example ? "<code>#{parameter.example.to_s.gsub("\n", "<br />")}</code>" : '<i>None</i>')%>
-              </td>
+            <% if parameter.is_xml_text? %>
+              | <span class="xml-flag">Value</span>
             <% end %>
-          <% end %>
+          </span>
+        <% end %>
+      <% end %>
+    </div>
+    <div class="oas-parameter-description">
 
-          <% unless model || callback %>
-            <td>
-              <% if parameter.raw['x-default-is-meta'] %>
-                <i><%= (parameter.default.nil? ? 'None' : parameter.default) %></i>
-              <% else %>
-                <% unless parameter.type == 'object' %>
-                  <%= (parameter.default.nil? ? '<i>None</i>' : "<code>#{parameter.default}</code>")%>
-                <% end %>
-              <% end %>
-            </td>
+      <div class="oas-parameter-meta">
+        <em>
+          <%= parameter.type %>
+          <% if parameter.format %>
+            (<%= parameter.format %>)
           <% end %>
 
-          <%
-            should_render_row = false
-            should_render_row = should_render_row || parameter.subproperties_are_one_of_many?
-            should_render_row = should_render_row || (parameter.properties && parameter.object? && parameter.properties.size.positive?)
-            should_render_row = should_render_row || (parameter.array? && parameter.items['properties'])
-          %>
-          <% if parameter.collection? && should_render_row %>
-
-            <tr class="Vlt-table__row--nohighlight">
-              <td colspan="4">
-                <% if parameter.subproperties_are_one_of_many? %>
-                  <div style="margin-left: 20px;">
-                    <h4>Any one of the following:</h4>
-                    <% parameter.properties.each do |property| %>
-                      <h5><%= property['description'] %></h5>
-                      <%= erb :'open_api/_parameters', locals: { parameters: property['properties'], model: model, format: format, callback: callback } %>
-                    <% end %>
-                  </div>
-                <% else %>
-                  <% if parameter.properties && parameter.object? && parameter.properties.size.positive? %>
-                    <%= erb :'open_api/_parameters', locals: { parameters: parameter.properties, model: model, format: format, callback: callback } %>
-                  <% end %>
-                  <% if parameter.array?
-                    items = parameter.items
-                    # Merge allOf entries
-                    if items['allOf']
-                      items = items['allOf'].reduce { |a,b| a.deep_merge(b) }
-                    end
-                    # Cast back to properties
-                    next unless items['properties']
-                    items['properties'] = items['properties'].map do |name, definition|
-                      OasParser::Property.new(nil, items, name, definition)
-                    end
-                    %>
-                    <%= erb :'open_api/_parameters', locals: { parameters: items['properties'], model: model, format: format, callback: callback } %>
-                  <% end %>
-                <% end %>
-              </td>
-            </tr>
+          <% 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 %>
-        </tr>
+
+        <% 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 %>
-    </tbody>
-  </table>
-</div>
+    <% 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 %>
+