jekyll-ramler 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dc0e1f14109050ea1f296cc5ed5b3fb1ac100510
+  data.tar.gz: fdf5cee7e082ea0397f460233683b1b13aa5e034
+SHA512:
+  metadata.gz: 54959f41e90effd0ab0af92512cc49780771e6bfb5cf204e5b725f81d24f70834396eff93c9f384ee49738cfd689eb0a34959e986ef36a6a6809476d36aa9a43
+  data.tar.gz: 4fe17f77d424cba1df92d33ce9ecb08d31179f25dfcdb03e3443f7aac569021897e50b7ce21c7d5783de3e54fad03dd7cdac006a076591eed616312faadfd87e

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 1.9.3-p547
+  - 2.1.5
+  - 2.2.0
+install:
+  - npm install raml-cop
+  - bundle install
+script: "bundle exec rspec"

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test, :development do
+  gem 'fakefs', require: 'fakefs/safe'
+  gem 'pry'
+  gem 'rspec'
+  gem 'ruby_deep_clone'
+end

data/Gemfile.lock

@@ -0,0 +1,103 @@
+PATH
+  remote: .
+  specs:
+    jekyll-ramler (0.0.1)
+      jekyll
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    blankslate (2.1.2.4)
+    celluloid (0.16.0)
+      timers (~> 4.0.0)
+    classifier-reborn (2.0.3)
+      fast-stemmer (~> 1.0)
+    coderay (1.1.0)
+    coffee-script (2.3.0)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.9.0)
+    colorator (0.1)
+    diff-lcs (1.2.5)
+    execjs (2.3.0)
+    fakefs (0.6.5)
+    fast-stemmer (1.0.2)
+    ffi (1.9.6)
+    hitimes (1.2.2)
+    jekyll (2.5.3)
+      classifier-reborn (~> 2.0)
+      colorator (~> 0.1)
+      jekyll-coffeescript (~> 1.0)
+      jekyll-gist (~> 1.0)
+      jekyll-paginate (~> 1.0)
+      jekyll-sass-converter (~> 1.0)
+      jekyll-watch (~> 1.1)
+      kramdown (~> 1.3)
+      liquid (~> 2.6.1)
+      mercenary (~> 0.3.3)
+      pygments.rb (~> 0.6.0)
+      redcarpet (~> 3.1)
+      safe_yaml (~> 1.0)
+      toml (~> 0.1.0)
+    jekyll-coffeescript (1.0.1)
+      coffee-script (~> 2.2)
+    jekyll-gist (1.1.0)
+    jekyll-paginate (1.1.0)
+    jekyll-sass-converter (1.3.0)
+      sass (~> 3.2)
+    jekyll-watch (1.2.1)
+      listen (~> 2.7)
+    kramdown (1.5.0)
+    liquid (2.6.2)
+    listen (2.8.5)
+      celluloid (>= 0.15.2)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+    mercenary (0.3.5)
+    method_source (0.8.2)
+    parslet (1.5.0)
+      blankslate (~> 2.0)
+    posix-spawn (0.3.9)
+    pry (0.10.1)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    pygments.rb (0.6.2)
+      posix-spawn (~> 0.3.6)
+      yajl-ruby (~> 1.2.0)
+    rb-fsevent (0.9.4)
+    rb-inotify (0.9.5)
+      ffi (>= 0.5.0)
+    redcarpet (3.2.2)
+    rspec (3.2.0)
+      rspec-core (~> 3.2.0)
+      rspec-expectations (~> 3.2.0)
+      rspec-mocks (~> 3.2.0)
+    rspec-core (3.2.0)
+      rspec-support (~> 3.2.0)
+    rspec-expectations (3.2.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-mocks (3.2.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-support (3.2.1)
+    ruby_deep_clone (0.6.0)
+    safe_yaml (1.0.4)
+    sass (3.4.11)
+    slop (3.6.0)
+    timers (4.0.1)
+      hitimes
+    toml (0.1.2)
+      parslet (~> 1.5.0)
+    yajl-ruby (1.2.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  fakefs
+  jekyll-ramler!
+  pry
+  rspec
+  ruby_deep_clone

data/LICENSE.md

@@ -0,0 +1,27 @@
+Copyright (c) 2015, GovDelivery, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without 
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this 
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, 
+   this list of conditions and the following disclaimer in the documentation 
+   and/or other materials provided with the distribution.
+
+3. Neither the name of GovDelivery nor the names of its contributors may be 
+   used to endorse or promote products derived from this software without 
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,53 @@
+[![Build Status](https://travis-ci.org/govdelivery/jekyll-ramler.svg?branch=master)](https://travis-ci.org/govdelivery/jekyll-ramler)
+[![Gem Version](https://badge.fury.io/rb/jekyll-ramler.svg)](http://badge.fury.io/rb/jekyll-ramler)
+
+jekyll-ramler
+=============
+
+Generates Jekyll pages for overview, security, and resource documentation 
+specificed in a RAML file.
+
+
+## Installation
+
+### Dependencies
+
+jekyll-ramler relies on [raml-cop](https://www.npmjs.com/package/raml-cop), a 
+Node.js script, to actually parse a RAML file. Thus, you will need to install
+[Node.js](http://nodejs.org/), then perform `npm install raml-cop`.
+
+
+## JSON Schema Support
+
+jekyll-ramler includes a few features for JSON Schema.
+
+### Table and Raw views of JSON Schema
+
+If a resource method defines `body:application/json:schema` item, then
+jekyll-ramler will generate two views of the schema. One view will be an
+easily copyable display of the raw schema. The other view will be a table-like
+display of parameters, similar to what is generated for 
+`body:application/x-www-form-urlencoded:formParamters`. 
+
+### Generated JSON Schema from formParameters
+
+Recognizing that Content-Type does not impact functionality or content for some
+APIs, jekyll-ramler will generate JSON Schema for resource methods that include
+a defined `body:application/x-www-form-urlencoded:formParamters` list, as well
+as a `body:application/json` item **without** a `schema` item. If a resource
+includes a `body:application/json/schema` item, then nothing will happen.
+
+## $ref and allOf
+
+[JSON Schema provides a semantic construct for schema inheritance](http://spacetelescope.github.io/understanding-json-schema/reference/combining.html)
+via the **$ref** and **allOf** keywords. jekyll-ramler uses this construct to
+allow for schema referred to in RAML to inherit from other schema, which allows
+you to DRY your JSON schema bit.
+
+When jekyll-ramler encounteres **$ref** and/or **allOf**, it pulls in and
+merges the referred to schemas, creating a single schema object that includes
+all attributes. Thus, while you might store your JSON schema across multiple
+files, users of your site will only see fully de-referenced and merged JSON
+schema on your site. This de-referencing and merging also allows jekyll-ramler
+to generate complete, table-like views of your JSON schema, even if your schema
+inherits from other schema.

data/jekyll-ramler.gemspec

@@ -0,0 +1,17 @@
+Gem::Specification.new do |s|
+  s.name        = 'jekyll-ramler'
+  s.version     = '0.0.1'
+  s.date        = '2015-02-09'
+  s.authors     = ['GovDelivery']
+  s.email       = 'support@govdelivery.com'
+  s.homepage    = 'https://github.com/govdelivery/jekyll-ramler'
+  s.license     = 'BSD-3-Cluase'
+  s.summary     = 'Jekyll plugin that generates API documentation pages based on RAML'
+  s.description = %q{Generates Jekyll pages for overview, security, and 
+                     resource documentation specificed in a RAML file.}
+
+  s.add_runtime_dependency  'jekyll'
+
+  s.files       = `git ls-files`.split($\)
+  s.require_paths = ['lib']
+end

data/lib/jekyll-ramler.rb

@@ -0,0 +1,2 @@
+require_relative 'utils'
+require_relative 'raml-generate'

data/lib/raml-generate.rb

@@ -0,0 +1,266 @@
+require 'json'
+
+module Jekyll
+  class RawFile<StaticFile
+    def initialize(site, base, dir, name, content)
+      @content = content
+      super(site, base, dir, name)
+    end
+
+    def write(dest)
+      dest_path = File.join(dest, @dir, @name)
+      FileUtils.mkdir_p(File.dirname(dest_path))
+      File.open(dest_path, 'w') do |f|
+        f.write(@content)
+      end
+    end
+  end
+
+  class GeneratedPage<Page
+    def initialize(site, base, dir, item, layout=nil)
+      @site = site
+      @base = base
+      @dir = dir.gsub(/{(\w*)}/, '--\1--').gsub(/\s/, '_')
+      @name = 'index.html'
+      
+      layout = get_layout(dir) if layout.nil?
+      layout << '.html' if not layout.end_with?('.html')
+
+      self.process(@name)
+      self.read_yaml(File.join(base, '_layouts'), layout)
+
+      self.data['title'] = "#{item['title']}"
+      if item.include?('description')
+        self.data['description'] = transform_md(item['description'])
+      end
+    end
+
+    private
+      def transform_md(output)
+        # Use the existing Jekyll Markdown converters
+        md_converters = site.converters.select{|c| c.matches('.md')}
+        md_converters.reduce(output) do |output, converter|
+          converter.convert output 
+        end
+      end
+
+      def get_layout(dir, site=@site)
+        default = site.config.fetch('defaults', {}).detect do |default| 
+          default['scope']['path'] == dir.split('/').first
+        end
+
+        default = {"values" => {}} if default.nil?
+
+        default['values'].fetch('layout', 'default')
+      end
+
+  end
+
+  class SecuritySchemePage<GeneratedPage
+    def initialize(site, base, dir, securityScheme)
+        super(site, base, dir, securityScheme, layout=get_layout('resource', site))
+    end
+  end
+
+  class DocumentationPage<GeneratedPage
+    def initialize(site, base, dir, documentation)
+      super(site, base, dir, documentation)
+
+      output = documentation['content']
+      self.data['body'] = transform_md(output)
+    end
+  end
+
+  class ResourcePage<GeneratedPage 
+    def initialize(site, base, dir, resource, traits, securitySchemes)
+      # Sandbox our resource, and do nothing with child resources
+      resource = resource.dup
+      resource.delete('resources')
+
+      resource['title'] = dir.sub('resource', '') if not resource.include?('title')
+      super(site, base, dir, resource)
+
+      # Add security data to the resource
+      resource.fetch('methods', []).each do |method|
+        if method.include?('securedBy')
+          for scheme in method['securedBy']
+            for attr in ['headers', 'queryParameters', 'responses']
+              method[attr] = {} if not method.include?(attr)
+              method[attr].merge!(securitySchemes[scheme].fetch('describedBy', {}).fetch(attr, {}))
+            end
+          end
+        end
+      end
+
+      # Add trait data to the resource
+      resource.fetch('methods', []).each do |method|
+        if method.include?('is')
+          for trait in method['is']
+            merge_method_trait(method, traits[trait])
+          end
+        end
+      end
+
+      # Compile JSON Schema that use $ref references
+      jsc = Jekyll::JsonSchemaCompiler.new
+      jsc.compile(resource['methods'])
+
+      # Generate new schema based on existing formParameters
+      schema_generator = Jekyll::RamlSchemaGenerator.new(site, resource['title'])
+      schema_generator.insert_schemas(resource['methods'])
+
+      # Transform descriptions via Markdown
+      resource = transform_resource_descriptions(resource)
+      self.data['methods'] = add_schema_hashes(resource['methods'])
+    end
+
+    private
+      def merge_method_trait(method, trait)
+        merger = proc { |key, v1, v2| Hash === v1 && Hash === v2 ? v1.merge(v2, &merger) : v2 }
+        method.merge(trait, &merger)
+
+        if method.include?('description')
+          method['description'] = "#{method['description']}\n\n#{trait['description']}"
+        else
+          method['description'] = trait['description']
+        end
+        method
+      end
+
+      def transform_resource_descriptions(resource)
+        if resource.include?('description')
+            resource['description'] = transform_md(resource['description'])
+        end
+
+        resource.each_key do |key|
+          if resource[key].is_a?(Hash)
+            resource[key] = transform_resource_descriptions(resource[key])
+          end
+          if resource[key].is_a?(Array)
+            resource[key].map!{|h| h.is_a?(Hash) ? transform_resource_descriptions(h) : h }
+          end
+        end
+
+        resource
+      end
+
+      # Adds a 'schema_hash' attribute to bodies with 'schema', which allows for the generation of schema table views
+      def add_schema_hashes(obj, key=nil)
+        if obj.is_a?(Array)
+          obj.map! { |method| add_schema_hashes(method) }
+        elsif obj.is_a?(Hash)
+          obj.each { |k, v| obj[k] = add_schema_hashes(v, k)}
+
+          if obj.include?("schema")
+            
+            case key
+              when 'application/json'
+                obj['schema_hash'] = JSON.parse(obj['schema'])
+
+                refactor_object = lambda do |obj|
+                  obj['properties'].each do |name, param|
+                    param['displayName'] = name
+                    param['required'] = true if obj.fetch('required', []).include?(name)
+
+                    if param.include?('example') and ['object', 'array'].include?(param['type'])
+                      param['example'] = JSON.pretty_generate(JSON.parse(param['example']))
+                    elsif param.include?('properties')
+                      param['example'] = JSON.pretty_generate(param['properties'])
+                    elsif param.include?('items')
+                      param['example'] = JSON.pretty_generate(param['items'])
+                    end
+
+                    obj['properties'][name] = param
+                  end
+                  obj
+                end
+
+                if obj['schema_hash'].include?('properties')
+                  obj['schema_hash'] = refactor_object.call(obj['schema_hash'])
+                end
+
+                if obj['schema_hash'].include?('items') and obj['schema_hash']['items'].include?('properties')
+                  obj['schema_hash']['items'] = refactor_object.call(obj['schema_hash']['items'])
+                end
+            end
+          end
+        end
+
+        obj
+      end
+  end
+
+  class ReferencePageGenerator < Generator
+    safe true
+
+    def generate(site)
+      @site = site
+
+      raml_js_path = site.config.fetch('raml_json_file_path', 'api.json')
+      raml_js = File.open(raml_js_path).read
+      raml_hash = JSON.parse(raml_js)
+
+      # BETTER THE DATASTRUCTURES!
+      @traits = {}
+      @securitySchemes = {}
+      if raml_hash.has_key?('traits')
+        raml_hash['traits'].each {|obj| obj.each_pair {|k, v| @traits[k] = v}}
+      end
+      if raml_hash.has_key?('securitySchemes')
+        raml_hash['securitySchemes'].each do |obj| 
+          obj.each_pair do |k, v| 
+            v.fetch('describedBy', {}).fetch('headers', {}).each_pair{ |hn, hv| hv['displayName'] = hn if not hv.nil?}
+            v.fetch('describedBy', {}).fetch('queryParameters', {}).each_pair{ |hn, hv| hv['displayName'] = hn if not hv.nil?}
+            @securitySchemes[k] = v
+          end
+        end
+      end
+
+      # Create a page for each resource
+      if raml_hash.has_key?('resources')
+        generate_resource_pages(raml_hash['resources'])
+      end
+
+      dir = Jekyll::get_dir('overview', @site.config) 
+      @securitySchemes.each do |scheme_name, scheme|
+        scheme_dir = File.join(dir, scheme_name)
+        scheme['title'] = scheme_name
+        @site.pages << SecuritySchemePage.new(@site, @site.source, scheme_dir, scheme) 
+      end
+
+      raml_hash.fetch('documentation', []).each do |documentation|
+        documentation_dir = File.join(dir, documentation['title'])
+        @site.pages << DocumentationPage.new(@site, @site.source, documentation_dir, documentation)
+      end
+
+      # Allow users to download the RAML, which may be modified since it was read
+      raml_download_path = site.config.fetch('raml_download_path', 'api.raml').split('/')
+      raml_download_filename = raml_download_path.delete_at(-1)
+      raml_download_path = raml_download_path.join('/') + '/'
+
+      raml_yaml = raml_hash.to_yaml
+      raml_yaml.sub!('---', '#%RAML 0.8')
+      @site.static_files << RawFile.new(@site, @site.source, raml_download_path, raml_download_filename, raml_yaml)
+    end
+
+    private
+      def generate_resource_pages(resources, parent_dir=nil)
+
+        if parent_dir
+          dir = parent_dir
+        else 
+          dir = Jekyll::get_dir('resource', @site.config)
+        end
+
+        resources.each do |resource|
+          resource_name = resource["relativeUri"]
+          resource_dir = File.join(dir, resource_name)
+          @site.pages << ResourcePage.new(@site, @site.source, resource_dir, resource, @traits, @securitySchemes)
+          if resource.has_key?('resources')
+            generate_resource_pages(resource['resources'], resource_dir)
+        end
+
+      end
+    end
+  end
+end

data/lib/utils.rb

@@ -0,0 +1,135 @@
+require 'json'
+
+module Jekyll
+  def self.get_dir(page_type, config)
+    config.fetch('page_dirs', {}).fetch(page_type, page_type)
+  end
+
+  def self.sanatize_json_string(s)
+      strip_newlines(s)
+  end
+
+  def self.strip_newlines(s)
+    # Assuming Markdown, so do NOT remove consecutive newlines
+    regex = /([^\n])\n([^\n])/
+    s.gsub(regex, '\1 \2').strip
+  end
+
+  # Utility class for creating schema (current JSON, perhaps XML someday) based
+  # on existing RAML formParameters 
+  class RamlSchemaGenerator
+
+
+    def initialize(site, title=nil)
+      @site = site
+      @title = title
+      @current_method = nil
+    end
+
+    # Creates a schema attribute sibling of any formParameter attribute found, 
+    # based on the found formParameters attribute.
+    #
+    # Existing schema siblings of formParameter attributes are not modified.
+    #
+    # Modifys obj, and returns the modified obj
+    def insert_schemas(obj)
+      if obj.is_a?(Array)
+        obj.map!{|method| insert_schemas(method)}
+      elsif obj.is_a?(Hash)
+        @current_method = obj['method'] if obj.include?('method')
+        
+        obj.each { |k, v| obj[k] = insert_schemas(v)}
+
+        if obj.include?('body')
+          if obj['body'].fetch('application/x-www-form-urlencoded', {}).include?('formParameters')
+            if obj['body'].include?('application/json') && !(obj['body']['application/json'].include?('schema'))
+              insert_json_schema(obj, generate_json_schema(obj))
+            end
+          end
+        end
+      end
+
+      obj
+    end
+
+    # Inserts provided JSON Schema into obj['body']['application/json']['schema'] 
+    def insert_json_schema(obj, schema)
+      obj['body']['application/json']['schema'] = schema 
+    end
+
+    # Creates JSON Schema - as a string - based on obj['body']['application/x-www-form-urlencoded']['formParameters'] 
+    def generate_json_schema(obj)
+
+      # JSON Schema spec: http://json-schema.org/latest/json-schema-validation.html
+      schema_hash = {}
+      schema_hash['$schema'] = @site.config['json_schema_schema_uri']
+      schema_hash['title'] = @title if @title
+      schema_hash['description'] = Jekyll::sanatize_json_string(obj['description']) if obj.include?('description')
+      schema_hash['type'] = 'object'
+
+      required_properties = []
+      schema_hash['properties'] = obj['body']['application/x-www-form-urlencoded']['formParameters'].dup
+      schema_hash['properties'].each do |name, param|
+        if param.include?('required')
+          required_properties << name if param['required'] == true
+          param.delete('required')
+        end
+
+        if param.include?('description')
+          param['description'] = Jekyll::sanatize_json_string(param['description']) 
+        end
+
+        # Repeat is not a supported keyword in JSON Schema 
+        if param.include?('repeat')
+          param.delete('repeat')
+        end
+      end
+      schema_hash['required'] = required_properties if not required_properties.empty?
+      
+      JSON.pretty_generate(schema_hash)
+    end
+  end
+
+  class JsonSchemaCompiler
+    def compile(obj, obj_name=nil)
+      if obj.is_a?(Array)
+        obj.map!{|method| compile(method)}
+      elsif obj.is_a?(Hash)
+        if obj.include?('schema') and obj_name == 'application/json'
+          schema_hash = JSON.parse(obj['schema']) 
+          schema_hash = traverse_and_compile_schema(schema_hash)
+          obj['schema'] = JSON.pretty_generate(schema_hash)
+        end
+        
+        obj.each { |k, v| obj[k] = compile(v, k)}
+      end
+
+      obj
+    end
+
+    private
+      def traverse_and_compile_schema(schema_hash)
+        if schema_hash.is_a?(Array)
+          schema_hash.map!{|method| traverse_and_compile_schema(method)}
+        elsif schema_hash.is_a?(Hash)
+          if schema_hash.include?('$ref')
+            refed = JSON.parse(File.read(schema_hash['$ref']))
+            schema_hash.delete('$ref')
+            schema_hash.merge!(refed)
+          end
+
+          schema_hash.each { |k, v| schema_hash[k] = traverse_and_compile_schema(v)}
+
+          # Merge allOfs into the parent object
+          if schema_hash.include?('allOf')
+            for item in schema_hash['allOf']
+              merger = proc { |key, v1, v2| Hash === v1 && Hash === v2 ? v1.merge(v2, &merger) : v2 }
+              schema_hash.merge!(item, &merger)
+            end
+            schema_hash.delete('allOf')
+          end
+        end
+        schema_hash 
+      end
+  end
+end

data/spec/reference_page_generator_spec.rb

@@ -0,0 +1,125 @@
+require_relative './spec_helper.rb'
+
+describe 'ReferencePageGenerator', fakefs:true do
+
+  before(:each) do
+    @site = Jekyll::Site.new(Jekyll.configuration({
+      "skip_config_files" => true,
+      "json_schema_schema_uri" => "http://json-schema.org/draft-04/schema#"
+    }))
+    @rpg = Jekyll::ReferencePageGenerator.new
+
+    FakeFS.activate!
+    Pry.config.history.should_save = false;
+    Pry.config.history.should_load = false;
+
+    FileUtils.mkdir_p('_layouts')
+    File.open('_layouts/default.html', 'w') { |f| f << "{{ content }}" }
+
+    File.open('api.json', 'w') do |f|
+      f << JSON.pretty_generate(load_simple_raml)
+    end
+
+  end
+
+  after(:each) do
+    FakeFS.deactivate!
+  end
+
+  context 'Generating Pages from RAML' do
+
+    it 'generates a resource page for each resource in the RAML' do
+      @rpg.generate(@site)
+
+      raml_hash = load_simple_raml
+      passed = recursive_resource_search(raml_hash, @site)
+      
+      expect(passed).to be true
+    end
+
+    it 'generates an overview page for each security or documentation item in the RAML' do
+      @rpg.generate(@site)
+      raml_hash = load_simple_raml
+
+      passed = documentation_search(raml_hash, @site)
+      expect(passed).to be true
+
+
+      passed = security_search(raml_hash, @site)
+      expect(passed).to be true
+
+    end
+
+    it 'transforms descriptions via Markdown' do 
+      @rpg.generate(@site)
+      super_security = @site.pages.select {|p| p.data['title'] == 'Super Security'}.first
+
+      expect(super_security.data['description']).to match /<p>.*<\/p>/m
+      expect(super_security.data['description']).to include "<em>secured</em>"
+
+      test_doc = @site.pages.select {|p| p.data['title'] == 'Some Test Content'}.first
+      expect(test_doc.data['body']).to match /<p>.*<\/p>\n\n<h1.*>.*<\/h1>\n\n<p>.*<\/p>/m
+      expect(test_doc.data['body']).to include "<strong>Hello</strong>"
+      
+      test_resource = @site.pages.select {|p| p.data['title'] == '/test_resource'}.first
+      test_post = test_resource.data['methods'].select {|r| r['method'] == 'post' }.first
+      test_post['body']['application/x-www-form-urlencoded']['formParameters'].each do |param|
+        expect(param[1]['description']).to match /<p>.*<\/p>/m
+      end
+    end
+
+    it 'inserts trait properties into resources that have traits' do
+      @rpg.generate(@site)
+
+      test_resource = @site.pages.select {|p| p.data['title'] == '/test_resource'}.first
+      test_post = test_resource.data['methods'].select {|r| r['method'] == 'post' }.first
+      expect(test_post['responses']).to include "418"
+      expect(test_post['responses']['418']['body']['application/json']['example']).to include "I'm a teapot"
+
+      # Should not insert a traits properties into pages that do not have that trait
+      @site.pages.delete(test_resource)
+      @site.pages.each do |page|
+        expect(page.data.to_s).not_to include "418"
+      end
+
+    end
+
+    it 'inserts security properties into resoruces that are secured' do
+      @rpg.generate(@site)
+
+      test_resource = @site.pages.select {|p| p.data['title'] == '/test_resource'}.first
+      test_post = test_resource.data['methods'].select {|r| r['method'] == 'post' }.first
+
+      expect(test_post['responses']).to include "401"
+      expect(test_post['responses']['401']['body']['application/json']['example']).to include "Whatcha doin' here?"
+      expect(test_post).to include "queryParameters"
+      expect(test_post['queryParameters']).to include "auth"
+      expect(test_post).to include "headers"
+      expect(test_post['headers']).to include "X-SUPER-SECURE"
+      expect(test_post['headers']['X-SUPER-SECURE']).to include "displayName"
+      expect(test_post['headers']['X-SUPER-SECURE']).to include "type"
+      expect(test_post['headers']['X-SUPER-SECURE']).to include "description"
+      expect(test_post['headers']['X-SUPER-SECURE']).to include "required"
+
+
+      # Should not insert security properties into pages that are not secured
+      @site.pages.delete(test_resource)
+      @site.pages.each do |page|
+        expect(page.data.to_s).not_to include "401"
+      end
+
+    end
+
+    it 'creates downloadable RAML and JSON of the API descriptor' do
+      @rpg.generate(@site)
+      @site.process
+      expect(File.file?(File.join('_site', 'api.raml'))).to be true
+      api_raml = File.read(File.join('_site', 'api.raml'))
+      expect(api_raml).to start_with "#%RAML 0.8"
+
+      expect(File.file?(File.join('_site', 'api.json'))).to be true
+      api_json = File.read(File.join('_site', 'api.json')) 
+      expect{JSON.parse(api_json)}.not_to raise_error 
+    end
+  end
+end

data/spec/spec_assets/json/schema/allOf_schema.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "allOf Schema",
+  "description": "An example of a schema with an allOf property",
+  "type": "object",
+  "allOf": [
+    { "properties": {
+        "foo": {
+          "description": "Fooing",
+          "type": "string",
+          "example": "Foo"
+        }
+      }
+    },
+    { "properties": {
+        "bar": {
+          "description": "A place to get a drink",
+          "type": "object"
+        }
+      }
+    }
+  ]
+}

data/spec/spec_assets/json/schema/foo.include.schema.json

@@ -0,0 +1,7 @@
+{
+    "foo": {
+    "description": "Fooing",
+    "type": "string",
+    "example": "Foo"
+  }
+}

data/spec/spec_assets/json/schema/ref_schema.schema.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "Ref Schema",
+  "description": "An example of a schema with a $ref",
+  "type": "object",
+  "properties": {
+    "$ref": "spec/spec_assets/json/schema/foo.include.schema.json"
+  }
+}

data/spec/spec_assets/json/schema/simple_schema.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "Simple Schema",
+  "description": "An example of a schema with no inheritance",
+  "type": "object",
+  "properties": {
+    "foo": {
+      "description": "Fooing",
+      "type": "string",
+      "example": "Foo"
+    },
+    "bar": {
+      "description": "A place to get a drink",
+      "type": "object"
+    }
+  }
+}

data/spec/spec_assets/raml/simple.raml

@@ -0,0 +1,73 @@
+#%RAML 0.8
+title: Test!
+documentation:
+  - title: Some Test Content
+    content: |
+      **Hello** and welcome to test content!
+
+      # Very Important Heading
+
+      This is all great!
+securitySchemes:
+  - "Super Security":
+      description: |
+        This is a description of the super secure system we employ to secure our
+        *secured* api.
+      type: x-{other}
+      describedBy:
+        headers:
+          X-SUPER-SECURE:
+            description: Super Secure auth token
+            type: string
+            required: true
+        queryParameters:
+          auth:
+        responses:
+          401:
+            body:
+              application/json:
+                example: |
+                  {
+                    "error": "Whatcha doin' here?"
+                  }
+  - "More Security":
+      description: |
+        This is a description of some more security we employ to secure our
+        *secured* api.
+      type: x-{other}
+traits:
+  - teapot:
+      usage: Used to test traits
+      responses: 
+        418:
+          body:
+            application/json:
+              example: |
+                {
+                  "status": "I'm a teapot"
+                }
+/test_resource:
+  post:
+    description: An example of a schema with no inheritance
+    is: [teapot]
+    securedBy: ["Super Security"]
+    body:
+      application/x-www-form-urlencoded:
+        formParameters:
+          foo:
+            description: Fooing
+            type: string
+            example:  Foo
+          bar:
+            description: A place to get a drink
+            type: string 
+  /nested_test_resource:
+    post:
+      description: An example of a nested resource
+      body:
+        application/x-www-form-urlencoded:
+          formParameters:
+            stuff:
+              description: Just some junk
+              type: string
+              example: Junk

data/spec/spec_helper.rb

@@ -0,0 +1,109 @@
+require 'deep_clone'
+require 'fakefs/spec_helpers'
+require 'jekyll'
+require 'pry'
+require 'rspec/expectations'
+require_relative '../lib/jekyll-ramler.rb'
+
+
+RSpec.configure do |config|
+  config.include FakeFS::SpecHelpers, fakefs:true
+end
+
+def pretty_json(json)
+  JSON.pretty_generate(JSON.parse(json))
+end
+
+def spec_pwd
+  spec_pwd = File.dirname(__FILE__)
+end
+
+def example_raml_hash
+  raml_hash = {
+    'title' => 'Test!',
+    'resources' => {
+      '/test_resource' => {
+        'post' => {
+          'description' => 'An example of a schema with no inheritance',
+          'body' => {
+            'application/x-www-form-urlencoded' => {
+              'formParameters' => {
+                'foo' => {
+                  'description' => 'Fooing',
+                  'type' => 'string',
+                  'example' => 'Foo'
+                },
+                'bar' => {
+                  'description' => 'A place to get a drink',
+                  'type' => 'object'
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+end
+
+def load_simple_raml
+  JSON.parse(`raml-cop #{File.join(spec_pwd, 'spec_assets/raml/simple.raml')} -j`)
+end
+
+def simple_schema
+  pretty_json(File.read(File.join(spec_pwd, 'spec_assets/json/schema/simple_schema.schema.json')))
+end
+
+def ref_schema
+  pretty_json(File.read(File.join(spec_pwd, 'spec_assets/json/schema/ref_schema.schema.json')))
+end
+
+def foo_bit
+  pretty_json(File.read(File.join(spec_pwd, 'spec_assets/json/schema/foo.include.schema.json')))
+end
+
+def allOf_schema
+  pretty_json(File.read(File.join(spec_pwd, 'spec_assets/json/schema/allOf_schema.schema.json')))
+end
+
+def recursive_resource_search(raml_hash, site, parent='')
+  passed = raml_hash['resources'].all? do |resource_hash|
+    site.pages.any? do |page|
+      page.data['title'] == "#{parent}#{resource_hash['relativeUri']}"
+    end
+  end
+
+  if passed
+    raml_hash['resources'].each do |resource_hash|
+      if resource_hash.include?('resources')
+        passed = recursive_resource_search(resource_hash, site, resource_hash['relativeUri'])
+      end
+    end
+  end
+
+  passed
+end
+
+def documentation_search(raml_hash, site)
+  raml_hash['documentation'].all? do |resource_hash|
+    site.pages.any? do |page|
+      page.data['title'] == resource_hash['title']
+    end
+  end
+end
+
+def security_search(raml_hash, site)
+  raml_hash['securitySchemes'].all? do |security_hash|
+    security_hash.all? do |name, hash|
+      site.pages.any? do |page|
+        page.data['title'] == name  
+      end
+    end
+  end
+end
+
+RSpec::Matchers.define :dereference do |expected_json|
+    match do |referenced_json|
+      !expected_json.include?('$ref') and referenced_json.all? {|k, v| expected_json[k] == v }
+    end
+end

data/spec/utils_json_schema_compiler_spec.rb

@@ -0,0 +1,87 @@
+require_relative './spec_helper.rb'
+
+describe 'Utils' do
+  context 'JSON Schema Compiler' do
+
+    before(:each) do
+      @jsc = Jekyll::JsonSchemaCompiler.new
+      @raml_hash = example_raml_hash
+    end
+
+    it 'does not modify an object that does not include a schema item for application/json' do
+      orig_raml_hash = DeepClone.clone @raml_hash
+      @raml_hash = @jsc.compile(@raml_hash)
+      expect(@raml_hash).to eq orig_raml_hash
+      
+      @raml_hash['resources']['/test_resource']['post']['body']['application/json'] = {
+        'example' => "{ 'bar' => {} }"
+      }
+      orig_raml_hash = DeepClone.clone @raml_hash
+      @raml_hash = @jsc.compile(@raml_hash)
+      expect(@raml_hash).to eq orig_raml_hash 
+    end
+
+    it 'does not modify an object with a schema item for application/json that does not include $ref or allOf' do
+      @raml_hash['resources']['/test_resource']['post']['body']['application/json'] = {
+        'schema' => simple_schema
+      }
+      orig_raml_hash = DeepClone.clone @raml_hash
+      @raml_hash = @jsc.compile(@raml_hash)
+      expect(@raml_hash).to eq orig_raml_hash
+    end
+
+
+    it 'replaces $ref items in application/json schema with the referred to content' do
+      @raml_hash['resources']['/test_resource']['post']['body']['application/json'] = {
+        'schema' => ref_schema
+      }
+      orig_raml_hash = DeepClone.clone @raml_hash
+
+      @raml_hash = @jsc.compile(@raml_hash)
+      orig_schema = orig_raml_hash['resources']['/test_resource']['post']['body']['application/json'].delete('schema')
+      orig_schema = JSON.parse(orig_schema)
+      new_schema = @raml_hash['resources']['/test_resource']['post']['body']['application/json'].delete('schema')
+      new_schema = JSON.parse(new_schema)
+
+      # The rest of the raml object should be identical
+      expect(@raml_hash).to eq(orig_raml_hash)
+
+      # Compiled, new_schema should include referred to properties
+      referenced_json = JSON.parse(foo_bit)
+      expect(new_schema['properties']).to dereference(referenced_json)
+
+      # The rest of the schema should be unchanged
+      referenced_json.each { |k, v| new_schema['properties'].delete(k) }
+      orig_schema['properties'].delete('$ref')
+      expect(new_schema).to eq(orig_schema)
+      
+    end
+
+    it 'merges allOf items into the parent object in application/json schema items' do
+      @raml_hash['resources']['/test_resource']['post']['body']['application/json'] = {
+        'schema' => allOf_schema
+      }
+      orig_raml_hash = DeepClone.clone @raml_hash
+
+      @raml_hash = @jsc.compile(@raml_hash)
+      orig_schema = orig_raml_hash['resources']['/test_resource']['post']['body']['application/json'].delete('schema')
+      orig_schema = JSON.parse(orig_schema)
+      new_schema = @raml_hash['resources']['/test_resource']['post']['body']['application/json'].delete('schema')
+      new_schema = JSON.parse(new_schema)
+
+      # The rest of the raml object should be identical
+      expect(@raml_hash).to eq(orig_raml_hash)
+
+      # Compiled, new_schema should have merged all of the allOf items
+      # allOf_schema properties *should* compile to be equal to *simple_schema* properties
+      expect(new_schema).not_to include('allOf')
+      expect(new_schema['properties']).to eq(JSON.parse(simple_schema)['properties'])
+
+      # The rest of the schema should be unchanged
+      orig_schema.delete('properties')
+      orig_schema.delete('allOf')
+      new_schema.delete('properties')
+      expect(new_schema).to eq(orig_schema)
+    end
+  end
+end

data/spec/utils_raml_schema_generator_spec.rb

@@ -0,0 +1,91 @@
+require_relative './spec_helper.rb'
+
+describe 'Utils' do
+  context 'RAML Schema Generator' do
+
+    before(:each) do 
+      @raml_hash = example_raml_hash
+      @site = Jekyll::Site.new(Jekyll.configuration({
+        "skip_config_files" => true,
+        "json_schema_schema_uri" => "http://json-schema.org/draft-04/schema#"
+      }))
+      @rsg = Jekyll::RamlSchemaGenerator.new(@site, 'Simple Schema')
+    end
+    context '.generate_json_schema' do
+      it 'creates a JSON Schema string that includes all properties from application/x-www-form-urlencoded:formParameters' do
+        json_schema = JSON.parse(@rsg.generate_json_schema(@raml_hash['resources']['/test_resource']['post']) )
+        expect(json_schema['properties']).to eq(JSON.parse(simple_schema)['properties'])
+      end
+
+      it 'creates a JSON Schema with a required attribute if application/x-www-form-urlencoded:formParameters includes a required parameter' do
+        @raml_hash['resources']['/test_resource']['post']['body']['application/x-www-form-urlencoded']['formParameters']['bar']['required'] = true
+        json_schema = JSON.parse(@rsg.generate_json_schema(@raml_hash['resources']['/test_resource']['post']))
+        expect(json_schema).to include('required')
+        expect(json_schema['required']).to include('bar')
+        expect(json_schema['properties']).to eq(JSON.parse(simple_schema)['properties'])
+
+      end
+
+      it 'throws an error if provided RAML does not include body:application/x-www-form-urlencoded:formParameters' do
+        body = @raml_hash['resources']['/test_resource']['post'].delete('body')
+        expect{@rsg.generate_json_schema(@raml_hash)}.to raise_error(NoMethodError)
+        @raml_hash['resources']['/test_resource']['post']['body'] = body
+        form = @raml_hash['resources']['/test_resource']['post']['body'].delete('application/x-www-form-urlencoded')
+        expect{@rsg.generate_json_schema(@raml_hash)}.to raise_error
+        @raml_hash['resources']['/test_resource']['post']['body']['application/x-www-form-urlencoded'] = form 
+        formParameters = @raml_hash['resources']['/test_resource']['post']['body']['application/x-www-form-urlencoded'].delete('formParameters') 
+        expect{@rsg.generate_json_schema(@raml_hash)}.to raise_error
+      end
+    end
+
+    context '.insert_json_schema' do
+      it 'inserts an appropriate string into application/json:schema' do
+        @raml_hash['resources']['/test_resource']['post']['body']['application/json'] = {}
+        orig_raml_hash = DeepClone.clone @raml_hash
+
+        json_schema = @rsg.generate_json_schema(@raml_hash['resources']['/test_resource']['post'])
+        @rsg.insert_json_schema(@raml_hash['resources']['/test_resource']['post'], json_schema)
+
+        expect(@raml_hash['resources']['/test_resource']['post']['body']['application/json']).to include('schema')
+        expect(@raml_hash['resources']['/test_resource']['post']['body']['application/json']['schema']).to eq(json_schema)
+        @raml_hash['resources']['/test_resource']['post']['body']['application/json'].delete('schema')
+        expect(@raml_hash).to eq(orig_raml_hash)
+      end
+
+      it 'throws an error if provided object does not have expected properties' do
+        expect{@rsg.insert_json_schema(@raml_hash, 'foobar')}.to raise_error
+      end
+    end
+
+    context '.insert_schemas' do
+      it 'inserts an appropriate JSON Schema string in application/json:schema' do
+        @raml_hash['resources']['/test_resource']['post']['body']['application/json'] = {}
+        orig_raml_hash = DeepClone.clone @raml_hash
+        @raml_hash = @rsg.insert_schemas(@raml_hash)
+        expect(@raml_hash['resources']['/test_resource']['post']['body']['application/json']).to include('schema')
+        expect(@raml_hash['resources']['/test_resource']['post']['body']['application/json']['schema']).to eq(pretty_json(simple_schema))
+
+        @raml_hash['resources']['/test_resource']['post']['body']['application/json'].delete('schema')
+        expect(@raml_hash).to eq(orig_raml_hash)
+      end
+
+      it 'does nothing if application/json:schema already exists' do
+        orig_schema = 'foobar'
+        @raml_hash['resources']['/test_resource']['post']['body']['application/json'] = { 'schema' => orig_schema }
+        orig_raml_hash = DeepClone.clone @raml_hash
+        @rsg.insert_schemas(@raml_hash) 
+
+        expect(@raml_hash).to eq(orig_raml_hash)
+        expect(@raml_hash['resources']['/test_resource']['post']['body']['application/json']['schema']).to eq(orig_schema)
+      end
+
+      it 'does nothing if there is no application/x-www-form-urlencoded:formParameters' do
+        @raml_hash['resources']['/test_resource']['post']['body']['application/x-www-form-urlencoded'].delete('formParameters')
+        orig_raml_hash = DeepClone.clone @raml_hash
+        @rsg.insert_schemas(@raml_hash) 
+
+        expect(@raml_hash).to eq(orig_raml_hash)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-ramler
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- GovDelivery
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: "Generates Jekyll pages for overview, security, and \n                     resource
+  documentation specificed in a RAML file."
+email: support@govdelivery.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .travis.yml
+- Gemfile
+- Gemfile.lock
+- LICENSE.md
+- README.md
+- jekyll-ramler.gemspec
+- lib/jekyll-ramler.rb
+- lib/raml-generate.rb
+- lib/utils.rb
+- spec/reference_page_generator_spec.rb
+- spec/spec_assets/json/schema/allOf_schema.schema.json
+- spec/spec_assets/json/schema/foo.include.schema.json
+- spec/spec_assets/json/schema/ref_schema.schema.json
+- spec/spec_assets/json/schema/simple_schema.schema.json
+- spec/spec_assets/raml/simple.raml
+- spec/spec_helper.rb
+- spec/utils_json_schema_compiler_spec.rb
+- spec/utils_raml_schema_generator_spec.rb
+homepage: https://github.com/govdelivery/jekyll-ramler
+licenses:
+- BSD-3-Cluase
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14
+signing_key: 
+specification_version: 4
+summary: Jekyll plugin that generates API documentation pages based on RAML
+test_files: []