RubyGems - avocado-docs - Versions diffs - 2.0.5 - Mend

avocado-docs 2.0.5

Files changed (33) hide show

checksums.yaml +7 -0
data/MIT-LICENSE +20 -0
data/Rakefile +21 -0
data/app/assets/javascripts/avocado/application.js +21 -0
data/app/assets/stylesheets/avocado/application.css.scss +163 -0
data/app/assets/stylesheets/avocado/bootstrap.css +5785 -0
data/app/controllers/avocado/avocado_controller.rb +22 -0
data/app/controllers/avocado/specs_controller.rb +4 -0
data/app/helpers/avocado/application_helper.rb +4 -0
data/app/models/avocado/endpoint.rb +13 -0
data/app/models/avocado/parser.rb +56 -0
data/app/models/avocado/request.rb +37 -0
data/app/models/avocado/resource.rb +17 -0
data/app/views/layouts/avocado/avocado.html.erb +14 -0
data/app/views/template.html.erb +54 -0
data/config/routes.rb +4 -0
data/lib/avocado.rb +31 -0
data/lib/avocado/cache.rb +20 -0
data/lib/avocado/config.rb +33 -0
data/lib/avocado/controller.rb +22 -0
data/lib/avocado/engine.rb +5 -0
data/lib/avocado/middleware.rb +37 -0
data/lib/avocado/middleware/defaults.rb +15 -0
data/lib/avocado/middleware/document_if_configuration.rb +12 -0
data/lib/avocado/middleware/document_metadata.rb +14 -0
data/lib/avocado/middleware/example_serialization.rb +10 -0
data/lib/avocado/middleware/request_serialization.rb +46 -0
data/lib/avocado/middleware/resource_serialization.rb +22 -0
data/lib/avocado/middleware/response_serialization.rb +19 -0
data/lib/avocado/rspec.rb +27 -0
data/lib/avocado/uploader.rb +26 -0
data/lib/avocado/version.rb +3 -0
metadata +159 -0

data/app/controllers/avocado/avocado_controller.rb ADDED

@@ -0,0 +1,22 @@
+module Avocado
+  class AvocadoController < ActionController::Base
+    def create
+      File.open(yaml, 'w+') { |f| f.write params[:file].read }
+      head :ok
+    end
+    def index
+      hash = YAML.load File.read(yaml)
+      @data = Avocado::Parser.new(hash)
+      render '/template'
+    end
+    private
+      def yaml
+        Avocado::Config.yaml_path.join('avocado.yml')
+      end
+  end
+end

data/app/controllers/avocado/specs_controller.rb ADDED

@@ -0,0 +1,4 @@
+module Avocado
+  class SpecsController < AvocadoController
+  end
+end

data/app/helpers/avocado/application_helper.rb ADDED

@@ -0,0 +1,4 @@
+module Avocado
+  module ApplicationHelper
+  end
+end

data/app/models/avocado/endpoint.rb ADDED

@@ -0,0 +1,13 @@
+module Avocado
+  class Endpoint
+    include ActiveModel::Model
+    attr_accessor :signature, :requests
+    def initialize(*)
+      @requests = SortedSet.new
+      super
+    end
+  end
+end

data/app/models/avocado/parser.rb ADDED

@@ -0,0 +1,56 @@
+module Avocado
+  class Parser
+    attr_reader :resources, :endpoints, :requests
+    def initialize(json)
+      @resources = SortedSet.new
+      @endpoints = Set.new
+      @requests  = Set.new
+      parse(json)
+    end
+    def resource(name)
+      @resources.find { |r| r.name == name }
+    end
+    private
+      def parse(json)
+        json.each do |req|
+          resource = find_or_create_resource_by_name req[:resource][:name]
+          endpoint = find_or_create_endpoint_by_signature resource, req[:request]
+          request  = instantiate_request_object_from(req)
+          request.endpoint = endpoint
+          if request.unique?(@requests)
+            endpoint.requests << request
+            resource.endpoints << endpoint
+            @resources << resource
+            @endpoints << endpoint
+            @requests  << request
+          end
+        end
+      end
+      def instantiate_request_object_from(params)
+        Avocado::Request.new \
+          path:        params[:request][:path],
+          params:      params[:request][:params],
+          headers:     params[:request][:headers],
+          status:      params[:response][:status],
+          body:        params[:response][:body],
+          description: params[:description]
+      end
+      def find_or_create_resource_by_name(name)
+         resource(name) || Avocado::Resource.new(name: name)
+      end
+      def find_or_create_endpoint_by_signature(resource, request)
+        signature = "#{request[:method]} #{request[:path]}"
+        resource.endpoints.find { |e| e.signature == signature } || Avocado::Endpoint.new(signature: signature)
+      end
+  end
+end

data/app/models/avocado/request.rb ADDED

@@ -0,0 +1,37 @@
+module Avocado
+  class Request
+    include ActiveModel::Model
+      attr_accessor :uid, :url, :path, :params, :status, :body, :headers
+      attr_accessor :endpoint, :description
+      def initialize(*)
+        super
+        self.uid = SecureRandom.hex
+      end
+      def ==(other)
+        other.path  == path &&
+        other.params == params &&
+        other.status == status &&
+        other.body == body
+      end
+      def <=>(other)
+        status <=> other.status
+      end
+      def unique?(requests)
+        requests.none? { |req| self == req }
+      end
+      def params
+        @params || {}
+      end
+      def body
+        @body || {}
+      end
+  end
+end

data/app/models/avocado/resource.rb ADDED

@@ -0,0 +1,17 @@
+module Avocado
+  class Resource
+    include ActiveModel::Model
+    attr_accessor :name, :endpoints
+    def initialize(*)
+      @endpoints = Set.new
+      super
+    end
+    def <=>(other)
+      name <=> other.name
+    end
+  end
+end

data/app/views/layouts/avocado/avocado.html.erb ADDED

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>API Docs</title>
+  <%= stylesheet_link_tag    "avocado/application", media: "all" %>
+  <%= javascript_include_tag "avocado/application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+<%= yield %>
+</body>
+</html>

data/app/views/template.html.erb ADDED

@@ -0,0 +1,54 @@
+<div id="avocado">
+  <ul id="sidebar">
+    <% @data.resources.each do |resource| %>
+      <li><a href="#<%= resource.name %>"><%= resource.name %></a></li>
+      <ul class="dropdown">
+        <% @data.resource(resource.name).endpoints.map(&:signature).uniq.each do |signature| %>
+          <li><a href="#<%= resource.name %>"><%= signature %></a></li>
+        <% end %>
+      </ul>
+    <% end %>
+  </ul>
+  <div id="requests">
+    <% @data.resources.each do |resource| %>
+      <a name="<%= resource.name %>"></a>
+      <h4><%= resource.name %></h4>
+      <ul class="request-endpoints">
+        <% resource.endpoints.each do |endpoint| %>
+          <% endpoint.requests.each do |request| %>
+            <li>
+              <a href="#" data-request-uid="<%= request.uid %>">
+                <span class="status"><%= request.status %></span>
+                <span class="url"><%= endpoint.signature %></span>
+                <span class="description"><%= request.description %></span>
+              </a>
+            </li>
+          <% end %>
+        <% end %>
+      </ul>
+    <% end %>
+  </div>
+  <div id="docs">
+    <% @data.requests.each do |req| %>
+      <div class="request" data-uid="<%= req.uid %>">
+        <h4><%= req.endpoint.signature %></h4>
+        <code class="request-parameters">
+<%= JSON.pretty_generate req.params.to_h %>
+        </code>
+        <code class="example-headers">
+          <% req.headers.each do |name, value| %>
+<%= name %>: <%= value %>
+          <% end %>
+        </code>
+        <code class="response-status"><%= req.status %></code>
+        <code class="response-body">
+<%= JSON.pretty_generate JSON[req.body] rescue '' %>
+          <div class="clearfix"></div>
+        </code>
+      </div>
+    <% end %>
+</div>

data/config/routes.rb ADDED

@@ -0,0 +1,4 @@
+Avocado::Engine.routes.draw do
+  root to: 'specs#index'
+  resources :specs, only: [:create]
+end

data/lib/avocado.rb ADDED

@@ -0,0 +1,31 @@
+require 'avocado/engine'
+require 'avocado/config'
+require 'avocado/uploader'
+require 'avocado/controller'
+require 'avocado/cache'
+require 'avocado/middleware'
+require 'avocado/middleware/defaults'
+require 'yaml'
+require 'net/http/post/multipart'
+module Avocado
+  @payload = []
+  class << self
+    attr_accessor :payload
+  end
+  def self.upload!
+    return if @payload.empty?
+    File.open('avocado.yml', 'w+') { |file| file.write payload.to_yaml }
+    Avocado::Uploader.new.upload('avocado.yml') if Avocado::Config.url
+  end
+  def self.reset!
+    self.payload = []
+    Avocado::Config.reset!
+    Avocado::Cache.clean
+  end
+end

data/lib/avocado/cache.rb ADDED

@@ -0,0 +1,20 @@
+# Temporarily store a JSON request/response. Ultimately RSpec will determine
+# if this request/response gets documented or not in an after(:each) block
+module Avocado
+  class Cache
+    class << self
+      attr_accessor :request, :response, :json
+      def store(request, response)
+        @json = {}
+        @request, @response = request, response
+      end
+      def clean
+        @json = @request = @response = nil
+      end
+    end
+  end
+end

data/lib/avocado/config.rb ADDED

@@ -0,0 +1,33 @@
+module Avocado
+  class Config
+    class << self
+      attr_accessor :url, :headers, :document_if, :yaml_path, :ignored_params
+      def configure(&block)
+        yield self
+      end
+      def headers
+        Array(@headers) || []
+      end
+      def document_if
+        @document_if || -> { true }
+      end
+      def yaml_path
+        @yaml_path || Rails.application.root
+      end
+      def ignored_params
+        @ignored_params ||= ['controller', 'action']
+      end
+      def reset!
+        @headers = @document_if = @yaml_path = @ignored_params = nil
+      end
+    end
+  end
+end

data/lib/avocado/controller.rb ADDED

@@ -0,0 +1,22 @@
+# This concern gets patched into ActionController::Base during testing
+# The after_action will ensure every request gets documented regardless of the
+# type of test (controller, integration, etc)
+module Avocado
+  module Controller
+    extend ActiveSupport::Concern
+    included do
+      after_action -> do
+        Avocado::Cache.clean
+        Avocado::Cache.store(request, response) if documentable?
+      end
+    end
+    def documentable?
+      response.body.blank? || !!JSON.parse(response.body)
+    rescue
+      false
+    end
+  end
+end

data/lib/avocado/engine.rb ADDED

@@ -0,0 +1,5 @@
+module Avocado
+  class Engine < ::Rails::Engine
+    isolate_namespace Avocado
+  end
+end

data/lib/avocado/middleware.rb ADDED

@@ -0,0 +1,37 @@
+module Avocado
+  class Middleware
+    attr_accessor :entries
+    def initialize
+      @entries = []
+    end
+    def <<(klass)
+      @entries << klass
+    end
+    def invoke(*args, &finally)
+      chain = entries.map(&:new).dup
+      traversal = -> (continue = true) do
+        return if !continue
+        if chain.empty?
+          finally.call
+        else
+          chain.shift.call(*args, &traversal)
+        end
+      end
+      traversal.call
+    end
+    def self.configure(&block)
+      @chain ||= new
+      yield @chain
+    end
+    def self.invoke(*args, &block)
+      @chain.invoke(*args, &block)
+    end
+  end
+end

data/lib/avocado/middleware/defaults.rb ADDED

@@ -0,0 +1,15 @@
+require 'avocado/middleware/document_metadata'
+require 'avocado/middleware/document_if_configuration'
+require 'avocado/middleware/request_serialization'
+require 'avocado/middleware/response_serialization'
+require 'avocado/middleware/resource_serialization'
+require 'avocado/middleware/example_serialization'
+Avocado::Middleware.configure do |chain|
+  chain << Avocado::Middleware::DocumentMetadata
+  chain << Avocado::Middleware::DocumentIfConfiguration
+  chain << Avocado::Middleware::RequestSerialization
+  chain << Avocado::Middleware::ResponseSerialization
+  chain << Avocado::Middleware::ResourceSerialization
+  chain << Avocado::Middleware::ExampleSerialization
+end

data/lib/avocado/middleware/document_if_configuration.rb ADDED

@@ -0,0 +1,12 @@
+module Avocado
+  class Middleware::DocumentIfConfiguration
+    # return false if document_if returns false, so it will
+    # stop the middleware chain and not upload anything
+    def call(*)
+      continue = Avocado::Config.document_if.call
+      yield continue
+    end
+  end
+end

data/lib/avocado/middleware/document_metadata.rb ADDED

@@ -0,0 +1,14 @@
+module Avocado
+  class Middleware::DocumentMetadata
+    # return false if the :document metadata is given and is explicitly false
+    def call(example, *)
+      if example.metadata[:document] == false
+        yield false
+      else
+        yield
+      end
+    end
+  end
+end

data/lib/avocado/middleware/example_serialization.rb ADDED

@@ -0,0 +1,10 @@
+module Avocado
+  class Middleware::ExampleSerialization
+    def call(example, *)
+      Avocado::Cache.json[:description] = example.description
+      yield
+    end
+  end
+end