ramlstyle 0.2.3

data/lib/ramlstyle/patch/root.rb

@@ -0,0 +1,35 @@
+module Raml
+  class Root
+    def path_name
+      ""
+    end
+
+    def name
+      "/"
+    end
+
+    def recursive_resources(resource)
+      resource.resources.values.inject(resource.resources.values) do |memo, sub_resource|
+        memo << recursive_resources(sub_resource)
+      end.flatten
+    end
+
+    def all_resources
+      recursive_resources(self)
+    end
+
+    def all_methods(method_filter = %w(get put post delete head options patch))
+      all_resources.collect do|r|
+        r.methods.values.select do |m|
+          method_filter.include?(m.name)
+        end
+      end.flatten
+    end
+
+    def all_responses
+      all_methods.collect do|m|
+        m.responses.values
+      end.flatten
+    end
+  end
+end

data/lib/ramlstyle/raml_parser.rb

@@ -0,0 +1,14 @@
+module Ramlstyle
+  class RamlParser
+    def initialize(file_name)
+      @file_name = file_name
+    end
+
+    # this expands out the resource_types, traits, and inline schemas
+    def parse
+      @raml ||= Raml.parse_file(@file_name)
+      @raml.expand
+      @raml
+    end
+  end
+end

data/lib/ramlstyle/review.rb

@@ -0,0 +1,68 @@
+module Ramlstyle
+  class Review
+    def initialize(raml)
+      @raml = raml
+    end
+
+    def review
+      # Root
+
+      lint(:error, "API Version (version) is required", @raml, &:version)
+
+      # Resources
+
+      lint(:warning, "Resource description is missing", @raml.all_resources, &:description)
+
+      lint(:warning, "Resource name should match standards", @raml.all_resources) do |resource|
+        resource.name =~ %r(^\/([a-z]+(\-[a-z]+)*|{[a-z]+([A-Z][a-z]+)*})$)
+      end
+
+      # Methods
+
+      lint(:warning, "Method should have description", @raml.all_methods, &:description)
+
+      lint(
+        :warning,
+        "Patch, Post, and Put Methods should have JSON bodies",
+        @raml.all_methods(%w(put post patch))) do |method|
+        method.bodies.keys.include?("application/json")
+      end
+
+      lint(
+        :warning,
+        "Patch, Post, and Put Methods should have JSON examples",
+        @raml.all_methods(%w(put post patch))) do |method|
+        method.bodies.keys.include?("application/json") &&
+          method.bodies["application/json"].example
+      end
+
+      lint(
+        :warning,
+        "Patch, Post, and Put Methods should have JSON schema",
+        @raml.all_methods(%w(put post patch))) do |method|
+        method.bodies.keys.include?("application/json") &&
+          method.bodies["application/json"].schema
+      end
+
+      # Responses
+
+      lint(:warning, "Response should have description", @raml.all_responses, &:description)
+
+      lint(:warning, "Responses should have JSON examples", @raml.all_responses) do |response|
+        response.bodies.keys.include?("application/json") &&
+          response.bodies["application/json"].example
+      end
+
+      lint(:warning, "Responses should have JSON schema", @raml.all_responses) do |response|
+        response.bodies.keys.include?("application/json") &&
+          response.bodies["application/json"].schema
+      end
+    end
+
+    def lint(severity, rule_name, nodes, &test)
+      Array(nodes).each do |node|
+        puts "#{severity.to_s.upcase}: #{rule_name} at #{node.path_name}" unless test.call(node)
+      end
+    end
+  end
+end

data/lib/ramlstyle/version.rb

@@ -0,0 +1,3 @@
+module Ramlstyle
+  VERSION = "0.2.3"
+end

data/lib/ramlstyle.rb

@@ -0,0 +1,33 @@
+require "erb"
+require "redcarpet"
+require "raml"
+
+require "ramlstyle/version"
+require "ramlstyle/patch/node"
+require "ramlstyle/patch/root"
+
+module Ramlstyle
+	module Command
+		autoload :CommandChain, 'ramlstyle/command/command_chain'
+		autoload :DocumentCommand, 'ramlstyle/command/document_command'
+		autoload :EndChain, 'ramlstyle/command/end_chain'
+		autoload :FileCommand, 'ramlstyle/command/file_command'
+		autoload :Options, 'ramlstyle/command/options'
+		autoload :ParseCommand, 'ramlstyle/command/parse_command'
+		autoload :ReviewCommand, 'ramlstyle/command/review_command'
+		autoload :Settings, 'ramlstyle/command/settings'
+	end
+
+	module Documentation
+		autoload :ERBContext, 'ramlstyle/documentation/erb_context'
+		autoload :Renderer, 'ramlstyle/documentation/renderer'
+		autoload :RendererFactory, 'ramlstyle/documentation/renderer_factory'
+	end
+
+	autoload :CLICommand, 'ramlstyle/cli_command'
+	autoload :Document, 'ramlstyle/document'
+	autoload :RamlParser, 'ramlstyle/raml_parser'
+	autoload :Review, 'ramlstyle/review'
+
+  TEMPLATES_PATH = File.join(File.dirname(File.expand_path(__FILE__)), '..', 'templates')
+end

data/ramlstyle.gemspec

@@ -0,0 +1,36 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ramlstyle/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "ramlstyle"
+  spec.version       = Ramlstyle::VERSION
+  spec.authors       = ["Mark Morga"]
+  spec.email         = ["markmorga@gmail.com"]
+
+  spec.summary       = "Cmd line tool to validate, lint, and document a RAML API."
+  spec.description   =
+    "Validates RAML file (and JSON schema), runs a configurable set of linting rules, and produces HTML documentation."
+  spec.homepage      = "http://github.com/rackerlabs/ramlstyle"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "redcarpet"
+  spec.add_runtime_dependency "raml_ruby"
+
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "rubocop"
+  spec.add_development_dependency "rubycritic"
+  spec.add_development_dependency "sandi_meter"
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "guard"
+  spec.add_development_dependency "guard-minitest"
+  spec.add_development_dependency "mocha"
+end

data/sandi_meter/.sandi_meter

@@ -0,0 +1,2 @@
+vendor
+test

data/templates/item.html.erb

@@ -0,0 +1,40 @@
+<li>
+  <% if @item.display_name %>
+    <strong><%= @item.display_name %></strong>:
+  <% else %>
+    <strong><%= @key %></strong>:
+  <% end %>
+
+  <em>
+    <% if @item.required %>required <% end %>
+    (
+    <% if @item.enum %>
+      one of <%= @item.enum.join(', ') %>
+    <% else %>
+      <%= @item.type %>
+    <% end %>
+
+    <% if @item.default %> - default: <%= @item.default %><% end %>
+    <% if @item.repeat %> - repeat: <%= @item.repeat %><% end %>
+    <% if @item.type == 'string' %>
+      <% if @item.min_length %> - min_length: <%= @item.min_length %><% end %>
+      <% if @item.max_length %> - max_length: <%= @item.max_length %><% end %>
+    <% else %>
+      <% if @item.minimum %> - minimum: <%= @item.minimum %><% end %>
+      <% if @item.maximum %> - maximum: <%= @item.maximum %><% end %>
+    <% end %>
+    <% if @item.pattern %> - pattern: <%= @item.pattern %><% end %>
+    )
+  </em>
+
+  <%= markdown(@item.description) %>
+
+  <% if @item.example %>
+    <p><strong>Example</strong>:</p>
+    <% if @item.type == 'string' %>
+      <pre><%= h(@item.example) %></pre>
+    <% else %>
+      <pre><code><%= h(@item.example) %></code></pre>
+    <% end %>
+  <% end %>
+</li>

data/templates/resource.html.erb

@@ -0,0 +1,184 @@
+<% if (@resource.methods || (@resource.description && @resource.parent_url)) %>
+  <div class="panel panel-white">
+    <div class="panel-heading">
+      <h4 class="panel-title">
+        <a class="collapsed" data-toggle="collapse" href="#panel_<%= @resource.unique_id %>">
+          <span class="parent"><%= @resource.parent_url %></span><%= @resource.name %>
+        </a>
+
+        <span class="methods">
+          <% for method in @resource.methods.values %>
+            <a class="collapsed" href="#panel_<%= @resource.unique_id %>" data-toggle="collapse" aria-expanded="false" aria-controls="panel_<%= @resource.unique_id %>">
+              <span class="badge badge_<%= method.name %>"><%= method.name %><% if secured?(method) %> <span class="glyphicon glyphicon-lock" title="Authentication required"></span><% end %></span>
+            </a>
+          <% end %>
+        </span>
+      </h4>
+    </div>
+
+    <div id="panel_<%= @resource.unique_id %>" class="panel-collapse collapse">
+      <div class="panel-body">
+        <% if @resource.parent_url %>
+          <% if @resource.description %>
+            <div class="@resource-description">
+              <%= markdown(@resource.description) %>
+            </div>
+          <% end %>
+        <% end %>
+
+        <div class="list-group">
+          <% for method in @resource.methods.values %>
+            <div onclick="window.location.href = '#<%= @resource.unique_id %>_<%= method.name %>'" data-toggle="collapse" href="#<%= @resource.unique_id %>_<%= method.name %>" aria-expanded="false" aria-controls="<%= @resource.unique_id %>_<%= method.name %>" class="list-group-item">
+              <span class="badge badge_<%= method.name %>"><%= method.name %><% if secured?(method) %> <span class="glyphicon glyphicon-lock" title="Authentication required"></span><% end %></span>
+              <div class="method_description">
+                <%= markdown method.description%>
+              </div>
+              <div class="clearfix"></div>
+            </div>
+            <div class="collapse" tabindex="0" id="<%= @resource.unique_id %>_<%= method.name %>">
+              <div class="panel panel-default">
+                <div class="panel-body">
+                  <% if secured?(method) %>
+                    <div class="alert alert-warning">
+                      <span class="glyphicon glyphicon-lock" title="Authentication required"></span> Secured by <%= security_scheme_names(method).join(", ") %>
+                    </div>
+                  <% end %>
+
+                  <!-- Nav tabs -->
+                  <ul class="nav nav-tabs">
+                    <% if method.all_uri_parameters.length || method.query_parameters || method.headers || method.body %>
+                      <li class="active">
+                        <a href="#<%= @resource.unique_id %>_<%= method.name %>_request" data-toggle="tab">Request</a>
+                      </li>
+                    <% end %>
+
+                    <% if method.responses %>
+                      <li>
+                        <a href="#<%= @resource.unique_id %>_<%= method.name %>_response" data-toggle="tab">Response</a>
+                      </li>
+                    <% end %>
+                  </ul>
+
+                  <!-- Tab panes -->
+                  <div class="tab-content">
+                    <% if method.all_uri_parameters.length || method.query_parameters || method.headers || method.body %>
+                      <div class="tab-pane active" id="<%= @resource.unique_id %>_<%= method.name %>_request">
+                        <% if @resource.all_uri_parameters.length %>
+                          <h3>URI Parameters</h3>
+                          <ul>
+                            <% for uri_parameter in @resource.all_uri_parameters %>
+                              <%= render_parameter(uri_parameter) %>
+                            <% end %>
+                          </ul>
+                        <% end %>
+
+                        <% if method.headers %>
+                          <h3>Headers</h3>
+                          <ul>
+                            <% for header_name, header in method.headers %>
+                              <%= render_parameter(header) %>
+                            <% end %>
+                          </ul>
+                        <% end %>
+
+                        <% if method.query_parameters %>
+                          <h3>Query Parameters</h3>
+                          <ul>
+                            <% for query_parameter in method.query_parameters.values %>
+                              <%= render_parameter(query_parameter) %>
+                            <% end %>
+                          </ul>
+                        <% end %>
+
+                        <% if method.bodies.count > 0 %>
+                          <h3>Body</h3>
+                          <% for method_type, method_body in method.bodies %>
+                            <p><strong>Type: <%= method_type %></strong></p>
+                            <% if method_body.form_parameters %>
+                              <strong>Form Parameters</strong>
+                              <ul>
+                                <% for form_param_name, form_param in method_body.form_parameters %>
+                                  <%= render_parameter(form_param) %>
+                                <% end %>
+                              </ul>
+                            <% end %>
+
+                            <% if method_body.schema %>
+                              <p><strong>Schema</strong>:
+                                  <span class="methods">
+                                    <a href="#<%= @resource.unique_id %>_<%= method.name %>_request_schema" data-toggle="collapse" aria-expanded="true" aria-controls="<%= @resource.unique_id %>_<%= method.name %>_request_schema"><span class="glyphicon glyphicon-collapse-down" title="collapse"></span></a>
+                                  </span>
+                                </p>
+
+                              <pre class="collapse" id="<%= @resource.unique_id %>_<%= method.name %>_request_schema"><code class="json-schema"><%= h(method_body.schema.value) %></code></pre>
+                            <% end %>
+
+                            <% if method_body.example %>
+                              <p><strong>Example</strong>:
+                                  <span class="methods">
+                                    <a href="#<%= @resource.unique_id %>_<%= method.name %>_request_example" data-toggle="collapse" aria-expanded="true" aria-controls="<%= @resource.unique_id %>_<%= method.name %>_request_example"><span class="glyphicon glyphicon-collapse-down" title="collapse"></span></a>
+                                  </span>
+                                </p>
+                              <pre class="collapse" id="<%= @resource.unique_id %>_<%= method.name %>_request_example"><code class="json example"><%= h(method_body.example) %></code></pre>
+                            <% end %>
+                          <% end %>
+                        <% end %>
+                      </div>
+                    <% end %>
+
+                    <% if method.responses %>
+                      <div class="tab-pane" id="<%= @resource.unique_id %>_<%= method.name %>_response">
+                        <% for status_code, response in method.responses %>
+                          <h2>HTTP status code <a href="http://httpstatus.es/<%= status_code %>" target="_blank"><%= status_code %></a></h2>
+                          <%= markdown response.description%>
+
+                          <% if response.headers %>
+                            <h3>Headers</h3>
+                            <ul>
+                              <% for header_name, header in response.headers %>
+                                <%= render_parameter(header) %>
+                              <% end %>
+                            </ul>
+                          <% end %>
+
+                          <% if response.bodies.count > 0 %>
+                            <h3>Body</h3>
+                            <% for response_key, response_body in response.bodies %>
+                              <p><strong>Type: <%= response_key %></strong></p>
+
+                              <% if response_body.schema %>
+                                <p><strong>Schema</strong>:
+                                  <span class="methods">
+                                    <a href="#<%= @resource.unique_id %>_<%= method.name %>_response_schema" data-toggle="collapse" aria-expanded="true" aria-controls="<%= @resource.unique_id %>_<%= method.name %>_response_schema"><span class="glyphicon glyphicon-collapse-down" title="collapse"></span></a>
+                                  </span>
+                                </p>
+                                <pre class="collapse" id="<%= @resource.unique_id %>_<%= method.name %>_response_schema"><code class="json-schema"><%= h(response_body.schema.value) %></code></pre>
+                              <% end %>
+
+                              <% if response_body.example %>
+                                <p><strong>Example</strong>:
+                                  <span class="methods">
+                                    <a href="#<%= @resource.unique_id %>_<%= method.name %>_response_example" data-toggle="collapse" aria-expanded="true" aria-controls="<%= @resource.unique_id %>_<%= method.name %>_response_example"><span class="glyphicon glyphicon-collapse-down" title="collapse"></span></a>
+                                  </span>
+                                </p>
+                                <pre id="<%= @resource.unique_id %>_<%= method.name %>_response_example" class="collapse"><code class="json example"><%= h(response_body.example) %></code></pre>
+                              <% end %>
+                            <% end %>
+                          <% end %>
+                        <% end %>
+                      </div>
+                    <% end %>
+                  </div>
+                </div>
+              </div>
+            </div>
+          <% end %>
+        </div>
+      </div>
+    </div>
+  </div>
+<% end %>
+
+<% for sub_resource in @resource.resources.values %>
+  <%= render_resource sub_resource %>
+<% end %>