apitome 0.0.8 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a1e1b44d0fcdb63bafd524f03297c31f51c4b523
-  data.tar.gz: f7ed3657e3e285f7aaae171fcf0337e3052108a2
+  metadata.gz: dc6b6b1d1b4087e335ccb621c5ca8c6af0c57489
+  data.tar.gz: 7fa8cfffd520e863cc3097b7eb1a0932786a2da4
 SHA512:
-  metadata.gz: f57528a4c1e0488e6a9b546f1cd99212fd889f082642cd6eb2a7744cad4c8526536d2f9a5d2325cbafbc840058f351845eaa1a6ce316527b33e561ea81e0e3d5
-  data.tar.gz: 3fe1abfa64a4fc598312173ff16702b8d2adbbab1959458322a754cf20fee6fd3462d8165bb33b285881e319659abe6787ce7a70bb037231183a091c6c18fd40
+  metadata.gz: f0d39922af9f8b5308923f654f733264f07604afd299a31a77553d4b67452bf2d1a247283b8c4aeab5fca4fe72c113f0c1d51494dab1392a45265b88972ab0b5
+  data.tar.gz: 9024d5502441305b8351119c9b8c97917c405605f0c7db46e1560c60a34c5c2f3913a6bf2fc9ba2f433b18ad3179d941e47cda6787e3d5e135cff542c01c0c3a

data/README.md

@@ -1,12 +1,21 @@
 Apitome
 =======
 
-[![Gem Version](https://badge.fury.io/rb/apitome.png)](http://badge.fury.io/rb/apitome)
-[![Code Climate](https://codeclimate.com/github/modeset/apitome.png)](https://codeclimate.com/github/modeset/apitome)
+[![Gem Version](https://img.shields.io/gem/v/apitome.svg)](https://rubygems.org/gems/apitome)
+[![Dependency Status](https://gemnasium.com/modeset/apitome.svg)](https://gemnasium.com/modeset/apitome)
+[![Build Status](https://img.shields.io/travis/modeset/apitome.svg)](https://travis-ci.org/modeset/apitome)
+[![Code Climate](https://img.shields.io/codeclimate/github/modeset/apitome.svg)](https://codeclimate.com/github/modeset/apitome)
+[![Test Coverage](https://codeclimate.com/github/modeset/apitome/badges/coverage.svg)](https://codeclimate.com/github/modeset/apitome)
+[![License](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)
 
-Apitome is a documentation tool for Rails that enhances [rspec_api_documentation](https://github.com/zipmark/rspec_api_documentation) (RAD). It's designed to display the documentation generated by RAD in either a single page (with scrollspy), or on individual pages, and uses Bootstrap3 for most of the basic styling and [highlight.js](https://github.com/isagalaev/highlight.js) for code highlighting.
+Apitome is a API documentation tool for Rails built on top of the great rspec DSL included in
+[rspec_api_documentation](https://github.com/zipmark/rspec_api_documentation) (RAD). It's designed to display the
+documentation generated by RAD in either a single page (with scrollspy), or on individual pages, and uses Bootstrap3 for
+most of the basic styling and [highlight.js](https://github.com/isagalaev/highlight.js) for code highlighting.
 
-You can provide a markdown file that will be displayed as the README page, and by taking advantage of its modular view structure you can override any number of views and partials to customize the output. You can also specify custom css and javascript if you want to do fancier things or change how it looks.
+You can provide a markdown file that will be displayed as the README page, and by taking advantage of its modular view
+structure you can override any number of views and partials to customize the output. You can also specify custom css and
+javascript if you want to do fancier things or change how it looks.
 
 
 ## Installation
@@ -23,7 +32,8 @@ Optionally run the install generator to get the initializer and an initial readm
 rails generate apitome:install
 ```
 
-Update your `spec_helper.rb` to adjust how RAD outputs its results -- Apitome reads these JSON files to generate the documentation.
+Update your `spec_helper.rb` to adjust how RAD outputs its results -- Apitome reads these JSON files to generate the
+documentation.
 
 ```ruby
 RspecApiDocumentation.configure do |config|
@@ -39,76 +49,20 @@ You can view your documentation at the default `api/docs` route.
 
 ## Configuration
 
-After installation, your app will have an apitome initializer (app/config/initializers/apitome.rb). You will find the following parameters that can be used to customize apitome. Note: Restart rails after changing any of these parameters.
-
-<dl>
-
-<dt> mount_at </dt><dd>
-  This determines where the Apitome routes will be mounted. Changing this to "/api/documentation" for instance would allow you to browse to http://localhost:3000/api/documentation to see your api documentation. Set to nil and mount it yourself if you need to.<br/>
-
-  <b>default:</b> <code>"/api/docs"</code>
-</dd>
-
-<dt> root </dt><dd>
-  This defaults to Rails.root if left nil. If you're providing documentation for an engine using a dummy application it can be useful to set this to your engines root.. E.g. <code>Application::Engine.root</code><br/>
-
-  <b>default:</b> <code>nil</code>
-</dd>
-
-<dt> doc_path </dt><dd>
-  This is where rspec_api_documentation outputs the JSON files. This is configurable within RAD, and so is configurable here.<br/>
-
-  <b>default:</b> <code>"doc/api"</code>
-</dd>
-
-<dt> title </dt><dd>
-  The title of the documentation -- If your project has a name, you'll want to put it here.<br/>
-
-  <b>default:</b> <code>"Apitome Documentation"</code>
-</dd>
-
-<dt> layout </dt><dd>
-  The main layout view for all documentation pages. By default this is pretty basic, but you may want to use your own application layout.<br/>
-
-  <b>default:</b> <code>"apitome/application"</code>
-</dd>
-
-<dt> code_theme </dt><dd>
-  We're using [highlight.js](https://github.com/isagalaev/highlight.js) for code highlighting, and it comes with some great themes. You can check [here for themes](http://softwaremaniacs.org/media/soft/highlight/test.html), and enter the theme as lowercase/underscore.<br/>
-
-  <b>default:</b> <code>"default"</code>
-</dd>
-
-<dt> css_override </dt><dd>
-  This allows you to override the css manually. You typically want to require `apitome/application` within the override, but if you want to override it entirely you can do so.<br/>
-
-  <b>default:</b> <code>nil</code>
-</dd>
-
-<dt> js_override </dt><dd>
-  This allows you to override the javascript manually. You typically want to require `apitome/application` within the override, but if you want to override it entirely you can do so.<br/>
-
-  <b>default:</b> <code>nil</code>
-</dd>
-
-<dt> readme </dt><dd>
-  You can provide a "README" style markdown file for the documentation, which is a useful place to include general information. This path is relative to your doc_path configuration.<br/>
-
-  <b>default:</b> <code>"../api.md"</code>
-</dd>
-
-<dt> single_page </dt><dd>
-  Apitome can render the documentation into a single page that uses scrollspy, or it can render the documentation on individual pages on demand. This allows you to specify which one you want, as a single page may impact performance.<br/>
-
-  <b>default:</b> <code>true</code>
-</dd>
+When you install Apitime an initializer file (app/config/initializers/apitome.rb) is generated that contains good
+documentation for each configuration directive. Otherwise you can get a refresher by checking the
+[Apitome Configuration](https://github.com/modeset/apitome/wiki/Apitome-Configuration) article.
 
 
 ## Customization
 
-You can put custom views and partials in your own `views/apitome/docs` -- check the repo here for [examples](https://github.com/modeset/apitome/tree/master/app/views/apitome/docs). You can put any partial in your own path and they will be overridden.
+You can put custom views and partials in your own `views/apitome/docs` -- check the repo here for
+[examples](https://github.com/modeset/apitome/tree/master/app/views/apitome/docs). You can put any partial in your own
+path and they will be overridden.
 
-Additional customization can come in the form of providing custom css and javascript. You can do this by creating the files you want (that often times require the default assets in the gem), and then configure Apitome to use those instead of the defaults.
+Additional customization can come in the form of providing custom css and javascript. You can do this by creating the
+files you want (that often times require the default assets in the gem), and then configure Apitome to use those instead
+of the defaults.
 
 
 ## License

data/app/controllers/apitome/docs_controller.rb

@@ -1,8 +1,17 @@
 class Apitome::DocsController < ActionController::Base
-
   layout Apitome.configuration.layout
 
-  helper_method :resources, :example, :formatted_body, :param_headers, :param_extras, :formatted_readme, :set_example, :id_for
+  helper_method *[
+    :resources,
+    :example,
+    :formatted_body,
+    :param_headers,
+    :param_extras,
+    :formatted_readme,
+    :set_example,
+    :id_for,
+    :rendered_markdown
+  ]
 
   def index
   end
@@ -10,16 +19,26 @@ class Apitome::DocsController < ActionController::Base
   def show
   end
 
+  def simulate
+    request = example["requests"][0]
+    if request
+      request["response_headers"].each { |k, v| headers[k] = v }
+      render text: request["response_body"], status: request["response_status"]
+    else
+      render text: "No simulation for this endpoint", status: 404
+    end
+  end
+
   private
 
   def file_for(file)
     file = Apitome.configuration.root.join(Apitome.configuration.doc_path, file)
-    raise Apitome::FileNotFound.new, "Unable to find #{file}" unless File.exists?(file)
+    raise Apitome::FileNotFoundError.new("Unable to find #{file}") unless File.exists?(file)
     File.read(file)
   end
 
   def resources
-    @resources ||= JSON.parse(file_for('index.json'))['resources']
+    @resources ||= JSON.parse(file_for("index.json"))["resources"]
   end
 
   def example
@@ -31,11 +50,16 @@ class Apitome::DocsController < ActionController::Base
   end
 
   def formatted_readme
+    return unless Apitome.configuration.readme
     file = Apitome.configuration.root.join(Apitome.configuration.doc_path, Apitome.configuration.readme)
+    rendered_markdown(file_for(file))
+  end
+
+  def rendered_markdown(string)
     if defined?(GitHub::Markdown)
-      GitHub::Markdown.render_gfm(file_for(file))
+      GitHub::Markdown.render(string)
     else
-      Kramdown::Document.new(file_for(file)).to_html
+      Kramdown::Document.new(string).to_html
     end
   end
 
@@ -53,18 +77,16 @@ class Apitome::DocsController < ActionController::Base
   def param_headers(params)
     titles = %w{Name Description}
     titles += param_extras(params)
+    titles
   end
 
   def param_extras(params)
-    extras = []
-    for param in params
-      extras += param.reject{ |k,v| %w{name description required scope}.include?(k) }.keys
-    end
-    extras.uniq
+    params.map do |param|
+      param.reject { |k, _v| %w{name description required scope}.include?(k) }.keys
+    end.flatten.uniq
   end
 
   def id_for(str)
-    str.gsub(/\.json$/, '').underscore.gsub(/[^0-9a-z]+/i, '-')
+    str.gsub(/\.json$/, "").underscore.gsub(/[^0-9a-z]+/i, "-")
   end
-
 end

data/app/views/apitome/docs/_all_examples.html.erb

@@ -2,8 +2,9 @@
   <section class="example" id="<%= id_for(resource['name']) %>">
     <h1 class="resource-name"><%= resource['name'] %></h1>
     <% resource['examples'].each do |example| %>
-      <article id="<%= id_for(example['link'].gsub('.json', '')) %>">
-        <%= render partial: 'example', locals: { example: set_example(example['link'].gsub('.json', '')) } %>
+      <% link = example['link'].gsub('.json', '') %>
+      <article id="<%= id_for(link) %>">
+        <%= render partial: 'example', locals: { example: set_example(link), link: link } %>
       </article>
     <% end %>
   </section>

data/app/views/apitome/docs/_endpoint.html.erb

@@ -0,0 +1,4 @@
+<section class="endpoint">
+  <h3><%= t(:endpoint) %></h3>
+  <pre><%= "#{method} #{endpoint}" %></pre>
+</section>

data/app/views/apitome/docs/_example.html.erb

@@ -1,6 +1,7 @@
 <h2><%= example['description'] %></h2>
 
 <%= render partial: 'apitome/docs/explanation',    locals: {explaination: example['explanation']} if example['explanation'] %>
+<%= render partial: 'apitome/docs/endpoint',       locals: {method: example['http_method'], endpoint: example['route']} %>
 <%= render partial: 'apitome/docs/params',         locals: {params: example['parameters']} if example['parameters'].size > 0 %>
 
 <% example['requests'].each_with_index do |request, index| %>
@@ -16,10 +17,11 @@
 
     <h3><%= t(:response) %></h3>
     <div class="response">
-      <%= render partial: 'apitome/docs/response_fields',   locals: {params: example['response_fields']}  if example['response_fields'].size > 0 %>
-      <%= render partial: 'apitome/docs/status',   locals: {request: request, index: index} %>
-      <%= render partial: 'apitome/docs/headers',  locals: {request: request, index: index, headers: request['response_headers']} %>
-      <%= render partial: 'apitome/docs/body',     locals: {request: request, index: index, body: request['response_body'], type: request['response_content_type']} if request['response_body'] %>
+      <%= link_to('Simulated Response', "#{Apitome.configuration.mount_at}/simulate/#{link}") %>
+      <%= render partial: 'apitome/docs/response_fields', locals: {params: example['response_fields']} if example['response_fields'].size > 0 %>
+      <%= render partial: 'apitome/docs/status',          locals: {request: request, index: index} %>
+      <%= render partial: 'apitome/docs/headers',         locals: {request: request, index: index, headers: request['response_headers']} %>
+      <%= render partial: 'apitome/docs/body',            locals: {request: request, index: index, body: request['response_body'], type: request['response_content_type']} if request['response_body'] %>
     </div>
   </div>
 <% end %>

data/app/views/apitome/docs/_explanation.html.erb

@@ -1,3 +1,3 @@
-<p class="explanation">
-  <%= raw example['explanation'] %>
-</p>
+<div class="explanation">
+  <%= raw rendered_markdown(example['explanation'].strip_heredoc) %>
+</div>

data/app/views/apitome/docs/_navigation.html.erb

@@ -1,11 +1,13 @@
 <ul class="nav sidenav">
-  <li>
-    <% if Apitome.configuration.single_page %>
-      <a href="#readme"><%= t(:readme) %></a>
-    <% else %>
-      <a href="<%= Apitome.configuration.mount_at %>"><%= t(:readme) %></a>
-    <% end %>
-  </li>
+  <% if Apitome.configuration.readme %>
+    <li>
+      <% if Apitome.configuration.single_page %>
+        <a href="#readme"><%= t(:readme) %></a>
+      <% else %>
+        <a href="<%= Apitome.configuration.mount_at %>"><%= t(:readme) %></a>
+      <% end %>
+    </li>
+  <% end %>
   <% resources.each do |resource| %>
     <li>
       <% if Apitome.configuration.single_page %>

data/app/views/apitome/docs/index.html.erb

@@ -1,6 +1,8 @@
-<section class="readme" id="readme">
-  <article>
-    <%= raw formatted_readme %>
-  </article>
-</section>
+<% if Apitome.configuration.readme %>
+  <section class="readme" id="readme">
+    <article>
+      <%= raw formatted_readme %>
+    </article>
+  </section>
+<% end %>
 <%= render 'all_examples' if Apitome.configuration.single_page %>

data/app/views/apitome/docs/show.html.erb

@@ -1,2 +1,2 @@
 <h1 class="resource-name"><%= example['resource'] %></h1>
-<%= render 'example' %>
+<%= render 'example', locals: { example: example, link: example['link'].gsub('.json', '') } %>

data/config/locales/en.yml

@@ -9,4 +9,5 @@ en:
   response: Response
   response_fields: Response Fields
   route: Route
+  endpoint: Endpoint
   status: Status

data/config/locales/es.yml

@@ -8,4 +8,5 @@ es:
   request: Solicitud
   response: Respuesta
   route: Ruta
+  endpoint: Punto de llegada
   status: Estado

data/config/routes.rb

@@ -1,4 +1,5 @@
 Apitome::Engine.routes.draw do
-  root to: 'docs#index'
-  get '/*path', to: 'docs#show'
+  root to: "docs#index"
+  get "/simulate/*path", to: "docs#simulate"
+  get "/*path", to: "docs#show"
 end

data/lib/apitome.rb

@@ -1,7 +1,7 @@
-require 'apitome/version'
-require 'apitome/exceptions'
-require 'apitome/configuration'
+require "kramdown"
 
-require 'apitome/engine'
+require "apitome/version"
+require "apitome/exceptions"
+require "apitome/configuration"
 
-require 'kramdown'
+require "apitome/engine"

data/lib/apitome/configuration.rb

@@ -1,19 +1,27 @@
-require "singleton"
-
 module Apitome
   class Configuration
-    include Singleton
+    cattr_accessor *[
+      :mount_at,
+      :root,
+      :doc_path,
+      :title,
+      :layout,
+      :code_theme,
+      :css_override,
+      :js_override,
+      :readme,
+      :single_page
+    ]
 
-    cattr_accessor :mount_at, :root, :doc_path, :title, :layout, :code_theme, :css_override, :js_override, :readme, :single_page
     @@mount_at     = "/api/docs"
     @@root         = nil # will default to Rails.root if left unset
-    @@doc_path     = 'doc/api'
-    @@title        = 'Apitome Documentation'
-    @@layout       = 'apitome/application'
-    @@code_theme   = 'default'
+    @@doc_path     = "doc/api"
+    @@title        = "Apitome Documentation"
+    @@layout       = "apitome/application"
+    @@code_theme   = "default"
     @@css_override = nil
     @@js_override  = nil
-    @@readme       = '../api.md'
+    @@readme       = "../api.md"
     @@single_page  = true
 
     def self.root=(path)

data/lib/apitome/engine.rb

@@ -2,7 +2,9 @@ module Apitome
   class Engine < ::Rails::Engine
     isolate_namespace Apitome
 
-    config.assets.precompile += %w( apitome/*.css apitome/*.js )
+    if config.respond_to? (:assets)
+      config.assets.precompile += %w{apitome/*.css apitome/*.js}
+    end
 
     initializer :assets, group: :all do |app|
       # default the root if it's not set
@@ -17,6 +19,5 @@ module Apitome
         end
       end
     end
-
   end
 end

data/lib/apitome/exceptions.rb

@@ -1,3 +1,7 @@
 module Apitome
-  class FileNotFound < Exception; end
+  class Error < StandardError
+  end
+
+  class FileNotFoundError < Apitome::Error
+  end
 end

data/lib/apitome/version.rb

@@ -1,3 +1,3 @@
 module Apitome
-  VERSION = "0.0.8"
+  VERSION = "0.1.0"
 end

data/lib/generators/apitome/install/install_generator.rb

@@ -5,10 +5,11 @@ module Apitome
 
       desc "Installs the Apitome initializer and markdown file into your application."
 
-      class_option :assets, type: :boolean,
+      class_option :assets,
+                   type: :boolean,
                    aliases: "-a",
                    default: false,
-                   desc:    "Install the javascript and stylesheet assets to /public"
+                   desc: "Install the javascript and stylesheet assets to /public"
 
       def copy_initializers
         copy_file "templates/initializer.rb", "config/initializers/apitome.rb"
@@ -24,7 +25,6 @@ module Apitome
       def display_readme
         readme "POST_INSTALL" if behavior == :invoke
       end
-
     end
   end
 end

data/lib/generators/apitome/install/templates/initializer.rb

@@ -1,9 +1,8 @@
 Apitome.setup do |config|
-
   # This determines where the Apitome routes will be mounted. Changing this to '/api/documentation' for instance would
   # allow you to browse to http://localhost:3000/api/documentation to see your api documentation. Set to nil and mount
   # it yourself if you need to.
-  config.mount_at = '/api/docs'
+  config.mount_at = "/api/docs"
 
   # This defaults to Rails.root if left nil. If you're providing documentation for an engine using a dummy application
   # it can be useful to set this to your engines root.. E.g. Application::Engine.root
@@ -11,19 +10,19 @@ Apitome.setup do |config|
 
   # This is where rspec_api_documentation outputs the JSON files. This is configurable within RAD, and so is
   # configurable here.
-  config.doc_path = 'doc/api'
+  config.doc_path = "doc/api"
 
   # The title of the documentation -- If your project has a name, you'll want to put it here.
-  config.title = 'Apitome Documentation'
+  config.title = "Apitome Documentation"
 
   # The main layout view for all documentation pages. By default this is pretty basic, but you may want to use your own
   # application layout.
-  config.layout = 'apitome/application'
+  config.layout = "apitome/application"
 
   # We're using highlight.js (https://github.com/isagalaev/highlight.js) for code highlighting, and it comes with some
   # great themes. You can check http://softwaremaniacs.org/media/soft/highlight/test.html for themes, and enter the
   # theme as lowercase/underscore.
-  config.code_theme = 'default'
+  config.code_theme = "default"
 
   # This allows you to override the css manually. You typically want to require `apitome/application` within the
   # override, but if you want to override it entirely you can do so.
@@ -35,10 +34,9 @@ Apitome.setup do |config|
 
   # You can provide a 'README' style markdown file for the documentation, which is a useful place to include general
   # information. This path is relative to your doc_path configuration.
-  config.readme = '../api.md'
+  config.readme = "../api.md"
 
   # Apitome can render the documentation into a single page that uses scrollspy, or it can render the documentation on
   # individual pages on demand. This allows you to specify which one you want, as a single page may impact performance.
   config.single_page = true
-
 end