nexmo-oas-renderer 0.1.0

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

@@ -0,0 +1,38 @@
+<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>
+      <h1 id="<%= group['name'].parameterize %>" class='Vlt-grey-dark'><%= group['name'] %></h1>
+      <p class: "Vlt-grey-darker"><%= group['description'] %></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 %>
+      <% end %>
+    </div>
+  </div>
+  <div class="Vlt-col Vlt-col--1of3 Nxd-api__code">
+    <% if group['schema'] %>
+      <% group['schema'].each do |format, schema| %>
+        <div class="js-format" data-format="<%= format %>">
+          <h5>Example Model</h5>
+          <%= ResponseParserDecorator.new(schema).html(format, xml_options: schema['xml']) %>
+        </div>
+      <% end %>
+    <% end %>
+  </div>
+</div>

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

@@ -0,0 +1,80 @@
+<div id="Vlt-sidenav" class="Vlt-sidenav Vlt-sidenav--light">
+  <div class="Vlt-sidenav__scroll">
+    <ul class="Vlt-sidemenu Vlt-sidemenu--rounded navigation">
+      <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>
+
+      <% @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| %>
+          <li>
+            <a href="#<%= endpoint.operationId %>" class="Vlt-sidemenu__link">
+              <svg class="Vlt-green"><use xlink:href="/assets/symbol/volta-icons.svg#Vlt-icon-code" /></svg>
+
+              <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 %>"><code class="Vlt-white"><%= endpoint.method %></code></span>
+            </a>
+          </li>
+
+          <% 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-blue"><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 %>
+
+        <% 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-orange"><use xlink:href="/assets/symbol/volta-icons.svg#Vlt-icon-mind-map" /></svg>
+                    <span class="Vlt-sidemenu__label"><%= endpoint.summary %></span>
+                  </a>
+                </li>
+              <% end %>
+            <% end %>
+          <% end %>
+        <% end %>
+
+        <% if name %>
+          </li>
+        <% end %>
+      <% end %>
+
+      <% if @specification.definition_errors %>
+        <li>
+          <a class="Vlt-sidemenu__link" href="#errors">Errors</a>
+        </li>
+      <% end %>
+      </li>
+    </ul>
+  </div>
+</div>

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

@@ -0,0 +1,50 @@
+<% 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] %>
+  <% 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 = allOf.reduce { |a,b| a.deep_merge(b) }
+        params = params['properties'].map do |name, definition|
+          OasParser::Property.new(nil, params, name, definition)
+        end
+      else
+        params = endpoint.request_body.properties_for_format(format)
+      end
+      if params
+    %>
+
+      <h4>
+        Request body
+        <span class="Vlt-badge Vlt-badge--blue"><%= format %></span>
+      </h4>
+
+      <%= erb :'open_api/_parameters', locals: { parameters: params, callback: callback } %>
+    <% end %>
+  <% else %>
+    <% endpoint.request_body.split_properties_for_format(format).each_with_index do |parameters, index| %>
+      <h4><%= parameters[0].schema['oneOf'][index]['description'] %></h4>
+      <%= erb :'open_api/_parameters', locals: { parameters: parameters, callback: callback } %>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,165 @@
+<%
+  model = false if model.nil?
+  callback = false if callback.nil?
+  format = nil if format.nil?
+%>
+
+<div class="Vlt-table Vlt-section Vlt-table--data 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| %>
+        <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.initialization_config && @specification.initialization_config['formats'] %>
+                <% if @specification.initialization_config['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.description}" : '<i>None</i>').render_markdown %>
+              <% end %>
+            <% else %>
+              <%= (parameter.description ? "#{parameter.description}" : '<i>None</i>').render_markdown %>
+            <% end %>
+
+            <% if parameter.enum %>
+              <br>
+              <small class="Vlt-grey-dark">
+                <%= (callback || model) ? "One of:" : "Must be one of:" %>
+                <%= parameter_values(parameter.enum) %>
+              </small>
+            <% 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>
+            <% 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>
+            <% end %>
+          <% end %>
+
+          <% 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>
+          <% end %>
+
+          <% if parameter.collection? %>
+            <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? %>
+                    <%= erb :'open_api/_parameters', locals: { parameters: parameter.properties, model: model, format: format, callback: callback } %>
+                  <% end %>
+                <% end %>
+              </td>
+            </tr>
+          <% end %>
+        <% end %>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

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

@@ -0,0 +1,61 @@
+<%
+  # @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'] %>
+  <% schema['properties'].each do |key, value| %>
+    <% next if key == '_links' %>
+    <% next if value['x-skip-response-description'] %>
+    <% anchor_value = "#{anchor_prefix}-#{key}" %>
+    <tr<% if value['properties'] %> class=" Vlt-table__row--noline" <% end %>>
+      <td id="<%= anchor_value %>">
+        <b><%= key %></b>
+        <% if value['items'] %>
+          <br />
+          <small>array of <%= value['items']['type'] %>s</small>
+        <% end %>
+      </td>
+      <td>
+        <%= value['description'] ? value['description'].render_markdown : '' %>
+        <% if value['enum']%>
+          <small class="Vlt-grey-dark">
+            One of: <%= parameter_values(value['enum']) %>
+          </small>
+        <% end %>
+
+        <% if value['items'] # If this is an array, we need to show the structure of the children %>
+          <% value['properties'] = value['items']['properties'] %>
+        <% end %>
+        <% if value['properties'] %>
+            </td>
+          </tr>
+          <tr class="Vlt-table__row--nohighlight">
+            <td colspan="2">
+              <div class="Vlt-table Vlt-table--data Vlt-table--bordered">
+                <table>
+                  <thead>
+                    <tr>
+                      <th>Field</th>
+                      <th>Description</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    <%= erb :'open_api/_response_description_parameters', locals: { schema: value, anchor_prefix: anchor_value } %>
+                  </tbody>
+                </table>
+              </div>
+        <% end %>
+      </td>
+    </tr>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,41 @@
+<% endpoint.responses.each do |response| %>
+  <% next unless response.success? %>
+  <% next if response.code.to_i == 204 %>
+  <% next unless response.content %>
+  <% id = SecureRandom.hex %>
+  <p class="collapsible">
+    <a class="Vlt-js-accordion__trigger Nxd-accordion-button" data-accordion="acc<%= id %>">
+      <span class="Vlt-btn Vlt-btn--tertiary Vlt-btn--block">
+        View response field descriptions
+      </span>
+    </a>
+  </p>
+
+  <div id="acc<%= id %>" class="Vlt-js-accordion__content <%= auto_expand_responses ? 'Vlt-js-accordion__content_open' : '' %>">
+    <h4 id="<%= anchor_prefix %>">Response Fields</h4>
+    <% response.formats.each_with_index do |format, index| %>
+      <div class="js-format" data-format="<%= format %>">
+        <div class="Vlt-table">
+          <table>
+            <thead>
+              <tr>
+                <th>Field</th>
+                <th>Description</th>
+              </tr>
+            </thead>
+            <tbody>
+              <% if response.exhibits_one_of_multiple_schemas?(format) %>
+                <% response.split_schemas(format).each_with_index do |schema, index| %>
+                  <%= erb :'open_api/_response_description_parameters', locals: { schema: schema, anchor_prefix: anchor_prefix } %>
+                <% end %>
+              <% else %>
+                <% schema = response.schema(format) %>
+                <%= erb :'open_api/_response_description_parameters', locals: { schema: schema, anchor_prefix: anchor_prefix } %>
+              <% end %>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    <% end %>
+  </div>
+<% end %>

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

@@ -0,0 +1,104 @@
+<% definition = @specification.definition %>
+<%= erb :'open_api/_navigation', locals: { definition: definition } %>
+
+<div class="Vlt-main Vlt-main--light Nxd-main" tabindex="2">
+  <div class="Vlt-card Vlt-article Nxd-api">
+    <div id="overview" class="Vlt-grid">
+      <div class="Vlt-col Vlt-col--2of3 Nxd-api__docs">
+        <div>
+          <h1>
+            <%= definition.info['title'] %>
+            <% if definition.info['x-label'] %>
+              <span class="Vlt-badge Vlt-badge--<%= definition.info['x-label'].parameterize %>">
+                <%= definition.info['x-label'] %>
+              </span>
+            <% end %>
+          </h1>
+
+          <% if definition.info['description'] %>
+            <p><%= definition.info['description'].render_markdown %></p>
+          <% end %>
+
+          <div class="Vlt-grid">
+            <div class="Vlt-col">
+              <a href=<%= url("#{request.url}.#{definition.format}", params: request.params) %> class='Vlt-btn Vlt-btn--secondary Vlt-btn--app'>
+                <svg><use xlink:href="/assets/symbol/volta-icons.svg#Vlt-icon-download" /></svg>
+                Download OpenAPI 3 Definition
+              </a>
+            </div>
+            <div class="Vlt-col Vlt-right">
+              <a href="https://github.com/Nexmo/api-specification/blob/master/definitions/<%= @specification.definition_name %>.yml" class='Vlt-btn Vlt-btn--tertiary Vlt-btn--app Vlt-right'>
+                <svg className="Vlt-icon Vlt-black">
+                  <use xlink:href="/assets/symbol/volta-icons.svg#Vlt-icon-github" />
+                </svg>
+                Improve this specification
+              </a>
+            </div>
+          </div>
+        </div>
+      </div>
+      <div class="Vlt-col Vlt-col--1of3 Nxd-api__code Nxd-api__code--install">
+
+        <% if @specification.display_initialization? %>
+          <div class="Nxd-api__code__header">
+            <% if @specification.initialization_config && @specification.initialization_config['formats'] %>
+              <div class="Vlt-native-dropdown">
+                <select class="js-format-selector">
+                  <% @specification.initialization_config['formats'].each do |value, name| %>
+                    <option value="<%= value %>"><%= name %></option>
+                  <% end %>
+                </select>
+              </div>
+            <% end %>
+          </div>
+          <%= @specification.initialization_content %>
+        <% end %>
+
+        <% if @specification.available_versions && @specification.available_versions.count > 1 %>
+          <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>
+
+    <% @specification.groups.each do |name, endpoints| %>
+      <% if name %>
+        <% group = definition.raw['tags'].select { |tag| tag['name'].capitalize == name.capitalize }.first %>
+        <%= erb :'open_api/_model', locals: { group: group } %>
+      <% end %>
+
+      <% endpoints.each do |endpoint| %>
+        <%= erb :'open_api/_endpoint', locals: { endpoint: endpoint } %>
+      <% end %>
+    <% end %>
+
+    <% if @specification.definition.raw['x-webhooks'] %>
+      <% @specification.definition.raw['x-webhooks'].each do |name, definition| %>
+        <%= erb :'open_api/_callback', locals: { callback: OasParser::Callback.new(self, name, definition), webhook: true } %>
+      <% end %>
+    <% end %>
+
+    <% if @specification.definition_errors %>
+      <div class="Vlt-grid" id="errors">
+        <div class="Vlt-col Vlt-col--2of3 Nxd-api__docs">
+          <div>
+            <%= @specification.definition_errors %>
+          </div>
+        </div>
+        <div class="Vlt-col Vlt-col--1of3 Nxd-api__code">
+          <h5>Example response</h5>
+          <%= Nexmo::OAS::Renderer::ResponseParserDecorator.new(definition.raw['components']['schemas']['Error']).html %>
+        </div>
+      </div>
+    <% end %>
+  </div>
+</div>