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

avocado-docs 2.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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