apitome 0.1.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: dc6b6b1d1b4087e335ccb621c5ca8c6af0c57489
-  data.tar.gz: 7fa8cfffd520e863cc3097b7eb1a0932786a2da4
+SHA256:
+  metadata.gz: efbf3bab00d3066329b5e4e13d06759c955126affdf49134524c53ca598e4cd7
+  data.tar.gz: 17eb4bdfe7ae58f73bc61a60e20e2326e8315c332992b63f43e3c5b28354b968
 SHA512:
-  metadata.gz: f0d39922af9f8b5308923f654f733264f07604afd299a31a77553d4b67452bf2d1a247283b8c4aeab5fca4fe72c113f0c1d51494dab1392a45265b88972ab0b5
-  data.tar.gz: 9024d5502441305b8351119c9b8c97917c405605f0c7db46e1560c60a34c5c2f3913a6bf2fc9ba2f433b18ad3179d941e47cda6787e3d5e135cff542c01c0c3a
+  metadata.gz: 50602b8235b8f3f6bc3499526044853f478a353de18d2117e135f749bf76aeb3222283a60613a6dc88a20b8118f15790b5f3a44e8fb7edd0b1b203194f1a77a8
+  data.tar.gz: 5e1c5b4dd2ecdd6db82f120a96ff7132defea2cf9e642acab80272f7821a854cd9b4f78e8e266bdb1a81b015033997073707419a390b4a32d3e44856fc148fbb

data/MIT.LICENSE

@@ -1,6 +1,6 @@
-Copyright 2013 Jeremy Jackson / ModeSet
+Copyright 2019 Jeremy Jackson / ModeSet
 
-https://github.com/modeset/teaspoon
+https://github.com/jejacks0n/apitome
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -2,24 +2,21 @@ 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)
+[![Build Status](https://img.shields.io/travis/jejacks0n/apitome.svg)](https://travis-ci.org/jejacks0n/apitome)
+[![Maintainability](https://api.codeclimate.com/v1/badges/eb8dd1c22f1da11b6c02/maintainability)](https://codeclimate.com/github/jejacks0n/apitome/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/eb8dd1c22f1da11b6c02/test_coverage)](https://codeclimate.com/github/jejacks0n/apitome/test_coverage)
+[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
 
-Apitome is a API documentation tool for Rails built on top of the great rspec DSL included in
+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.
+documentation generated by RAD in either a single page, or on individual pages, and uses Bootstrap 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.
 
-
 ## Installation
-
 Add it to your Gemfile.
 
 ```ruby
@@ -32,6 +29,8 @@ Optionally run the install generator to get the initializer and an initial readm
 rails generate apitome:install
 ```
 
+You can get the assets installed using the generator by providing a `--assets` flag.
+
 Update your `spec_helper.rb` to adjust how RAD outputs its results -- Apitome reads these JSON files to generate the
 documentation.
 
@@ -41,36 +40,142 @@ RspecApiDocumentation.configure do |config|
 end
 ```
 
-
 ## Usage
-
 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> parent_controller </dt><dd>
+  Set the parent controller that Apitome::DocsController will inherit from. Useful if you want to use a custom
+  <code>before_action</code> for instance.
+  <br/>
+  <b>default:</b> <code>"ActionController::Base"</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 <code>apitome/application</code> 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 <code>apitome/application</code> 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>
+
+<dt> url_formatter </dt><dd>
+  You can specify how urls are formatted using a Proc or other callable object.  Your proc will be called with a
+  resource name or link, giving you the opportunity to modify it as necessary for in the documentation url.
+  <br/>
+  <b>default:</b> <code>-> (str) { str.gsub(/\.json$/, '').underscore.gsub(/[^0-9a-z]+/i, '-') }</code>
+</dd>
+
+<dt> remote_url </dt><dd>
+  You can setup the docs to be loaded from a remote URL if they are not available in the application environment. This
+  URL is used as the base location and should be set to where the readme is located. If left nil, local is assumed.
+  <br/>
+  <b>default:</b> <code>nil</code>
+</dd>
+
+<dt> http_basic_authentication </dt><dd>
+  If using remote urls you can fetch the remote docs using HTTP Basic Authentication by configuring this to be an
+  array of the user and password. (E.g. <code>['user', 'password']</code>)
+  <br/>
+  <b>default:</b> <code>nil</code>
+</dd>
+
+<dt> precompile_assets </dt><dd>
+  By default all assets that ship with this library are precompiled by the asset pipeline. If you would prefer to
+  control this yourself, you can disable it by changing this to false.
+  <br/>
+  <b>default:</b> <code>true</code>
+</dd>
+
+<dt> simulated_response </dt><dd>
+  If <code>simulated_response</code> is disabled you can hide the "Simulated Response" links.
+  <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
+[here for examples](https://github.com/jejacks0n/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.
 
-
 ## License
-
 Licensed under the [MIT License](http://creativecommons.org/licenses/MIT/)
 
-Copyright 2013 [Mode Set](https://github.com/modeset)
-
+Copyright 2016 [jejacks0n](https://github.com/jejacks0n)
 
 ## Make Code Not War
-![crest](https://secure.gravatar.com/avatar/aa8ea677b07f626479fd280049b0e19f?s=75)

data/app/assets/javascripts/apitome/application.js

@@ -14,3 +14,19 @@ jQuery(function(){
   })
 });
 
+$(document).ready(function() {
+  $(window).scroll(function(){
+    if ($(this).scrollTop() > 1500) {
+      $('#scroll-to-top').removeClass('hidden').affix({
+        offset: { top:100 }
+      });
+    } else {
+      $('#scroll-to-top').addClass('hidden')
+    }
+  });
+  
+  $("#scroll-to-top").click(function(){
+    $('html, body').animate({scrollTop : 0},500);
+    return false;
+  });
+});

data/app/assets/stylesheets/apitome/application.css

@@ -135,3 +135,13 @@ body.single-page .docs-section > section.readme article {
   }
 }
 
+.sidebar {
+  overflow: auto;
+  max-height: 550px;
+}
+
+#scroll-to-top.affix {
+  position: fixed; /* keeps it on the bottom once in view */
+  bottom: 18px;
+  right: 1px;
+}

data/app/controllers/apitome/docs_controller.rb

@@ -1,7 +1,9 @@
-class Apitome::DocsController < ActionController::Base
+require "open-uri"
+
+class Apitome::DocsController < Object.const_get(Apitome.configuration.parent_controller)
   layout Apitome.configuration.layout
 
-  helper_method *[
+  helper_method(*[
     :resources,
     :example,
     :formatted_body,
@@ -11,7 +13,7 @@ class Apitome::DocsController < ActionController::Base
     :set_example,
     :id_for,
     :rendered_markdown
-  ]
+  ])
 
   def index
   end
@@ -22,71 +24,90 @@ class Apitome::DocsController < ActionController::Base
   def simulate
     request = example["requests"][0]
     if request
+      request["response_headers"].delete("Content-Length")
       request["response_headers"].each { |k, v| headers[k] = v }
-      render text: request["response_body"], status: request["response_status"]
+      render body: request["response_body"], status: request["response_status"]
     else
-      render text: "No simulation for this endpoint", status: 404
+      render body: "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::FileNotFoundError.new("Unable to find #{file}") unless File.exists?(file)
-    File.read(file)
-  end
+    def file_for(file, readme: false)
+      if Apitome.configuration.remote_url
+        file = readme ? file : "#{Apitome.configuration.doc_path}/#{file}"
+        file = CGI.escape("#{Apitome.configuration.remote_url}/#{file}")
+      else
+        file = Apitome.configuration.root.join(Apitome.configuration.doc_path, file)
+        raise Apitome::FileNotFoundError.new("Unable to find #{file}") unless File.exist?(file)
+      end
 
-  def resources
-    @resources ||= JSON.parse(file_for("index.json"))["resources"]
-  end
+      open(file, file_opts).read
+    end
 
-  def example
-    @example ||= JSON.parse(file_for("#{params[:path]}.json"))
-  end
+    def resources
+      @resources ||= JSON.parse(file_for("index.json"))["resources"]
+    end
 
-  def set_example(resource)
-    @example = JSON.parse(file_for("#{resource}.json"))
-  end
+    def example
+      @example ||= JSON.parse(file_for("#{params[:path]}.json"))
+    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 set_example(resource)
+      @example = JSON.parse(file_for("#{resource}.json"))
+    end
 
-  def rendered_markdown(string)
-    if defined?(GitHub::Markdown)
-      GitHub::Markdown.render(string)
-    else
-      Kramdown::Document.new(string).to_html
+    def file_opts
+      if Apitome.configuration.remote_url && Apitome.configuration.http_basic_authentication
+        { http_basic_authentication: Apitome.configuration.http_basic_authentication }
+      else
+        nil
+      end
     end
-  end
 
-  def formatted_body(body, type)
-    if type =~ /json/ && body.present?
-      JSON.pretty_generate(JSON.parse(body))
-    else
-      body
+    def formatted_readme
+      return unless Apitome.configuration.readme
+      rendered_markdown(file_for(Apitome.configuration.readme, readme: true))
     end
-  rescue JSON::ParserError
-    return body if body == " "
-    raise JSON::ParserError
-  end
 
-  def param_headers(params)
-    titles = %w{Name Description}
-    titles += param_extras(params)
-    titles
-  end
+    def rendered_markdown(string)
+      if defined?(GitHub::Markdown)
+        GitHub::Markdown.render(string)
+      else
+        Kramdown::Document.new(string).to_html
+      end
+    end
 
-  def param_extras(params)
-    params.map do |param|
-      param.reject { |k, _v| %w{name description required scope}.include?(k) }.keys
-    end.flatten.uniq
-  end
+    def formatted_body(body, type)
+      return body if body == " "
+      return body if body == "[binary data]" # see https://github.com/zipmark/rspec_api_documentation/blob/560c3bdc7bd5581e7c223334390221ecfc910be8/lib/rspec_api_documentation/client_base.rb#L88-L96
+      if type =~ /json/ && body.present?
+        JSON.pretty_generate(JSON.parse(body))
+      else
+        body
+      end
+    rescue => e
+      if Apitome.configuration.formatted_body_error_handler
+        Apitome.configuration.formatted_body_error_handler.call(e, body, type)
+      else
+        raise
+      end
+    end
 
-  def id_for(str)
-    str.gsub(/\.json$/, "").underscore.gsub(/[^0-9a-z]+/i, "-")
-  end
+    def param_headers(params)
+      titles = %w{Name Description}
+      titles += param_extras(params)
+      titles
+    end
+
+    def param_extras(params)
+      params.map do |param|
+        param.reject { |k, _v| %w{name description required scope}.include?(k) }.keys
+      end.flatten.uniq
+    end
+
+    def id_for(str)
+      Apitome.configuration.url_formatter.call(str)
+    end
 end

data/app/helpers/apitome/docs_helper.rb

@@ -0,0 +1,19 @@
+module Apitome::DocsHelper
+  def format_scope(scopes)
+    Array(scopes).each_with_index.map do |scope, index|
+      index == 0 ? scope : "[#{scope}]"
+    end.join
+  end
+
+  def resource_link(resource)
+    "#{Apitome.configuration.mount_at}/#{CGI.escape(resource['examples'].first['link'].gsub(/\.json$/, ''))}"
+  end
+
+  def example_link(example)
+    "#{Apitome.configuration.mount_at}/#{CGI.escape(example['link'].gsub(/\.json$/, ''))}"
+  end
+
+  def link_active?(link)
+    current_page?(url_for(link))
+  end
+end

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

@@ -1,10 +1,13 @@
 <% resources.each do |resource| %>
   <section class="example" id="<%= id_for(resource['name']) %>">
     <h1 class="resource-name"><%= resource['name'] %></h1>
+
+    <%= render partial: 'resource_explanation', locals: { explanation: resource['explanation'] } if resource['explanation'] %>
+
     <% resource['examples'].each do |example| %>
-      <% link = example['link'].gsub('.json', '') %>
+      <% link = example['link'].gsub(/.json$/, '') %>
       <article id="<%= id_for(link) %>">
-        <%= render partial: 'example', locals: { example: set_example(link), link: link } %>
+        <%= render partial: 'example', locals: { example: set_example(link).merge!(link: link) } %>
       </article>
     <% end %>
   </section>

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

@@ -1,4 +1,4 @@
 <section class="body">
-  <h4><%= t(:body) %></h4>
+  <h4><%= t(:body, scope: :apitome) %></h4>
   <pre><code class="<%= type %>"><%= formatted_body(body, type) %></code></pre>
 </section>

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

@@ -1,4 +1,4 @@
 <section class="curl">
-  <h4><%= t(:curl) %></h4>
+  <h4><%= t(:curl, scope: :apitome) %></h4>
   <pre><%= request['curl'] %></pre>
 </section>

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

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

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

@@ -6,22 +6,44 @@
 
 <% example['requests'].each_with_index do |request, index| %>
   <div id="<%= "request-#{index}" %>">
-    <h3><%= t(:request) %></h3>
+    <h3><%= t(:request, scope: :apitome) %></h3>
     <div class="request">
+      <% begin %>
       <%= render partial: 'apitome/docs/route',    locals: {request: request, index: index} %>
       <%= render partial: 'apitome/docs/headers',  locals: {request: request, index: index, headers: request['request_headers']} %>
       <%= render partial: 'apitome/docs/query',    locals: {request: request, index: index} unless request['request_query_parameters'].empty? %>
       <%= render partial: 'apitome/docs/body',     locals: {request: request, index: index, body: request['request_body'], type: request['request_content_type']} if request['request_body'] %>
       <%= render partial: 'apitome/docs/curl',     locals: {request: request, index: index} if request['curl'] %>
+      <%
+        rescue => e
+          if Apitome.configuration.example_error_handler
+            Apitome.configuration.example_error_handler.call(e, "request", request)
+          else
+            raise
+          end
+        end
+      %>
     </div>
 
-    <h3><%= t(:response) %></h3>
+    <h3><%= t(:response, scope: :apitome) %></h3>
     <div class="response">
-      <%= link_to('Simulated Response', "#{Apitome.configuration.mount_at}/simulate/#{link}") %>
+      <% begin %>
+      <%- if Apitome.configuration.simulated_response %>
+        <%= link_to('Simulated Response', simulated_path(example[:link])) if example[:link].present? %>
+      <%- end %>
       <%= 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'] %>
+      <%
+        rescue => e
+          if Apitome.configuration.example_error_handler
+            Apitome.configuration.example_error_handler.call(e, "response", request)
+          else
+            raise
+          end
+        end
+      %>
     </div>
   </div>
 <% end %>

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

@@ -1,4 +1,6 @@
-<section class="headers">
-  <h4><%= t(:headers) %></h4>
-  <pre><code class="http"><%= headers.map{ |k,v| "#{k}: #{v}" }.join("\n") %></code></pre>
-</section>
+<% unless headers.blank? %>
+  <section class="headers">
+    <h4><%= t(:headers, scope: :apitome) %></h4>
+    <pre><code class="http"><%= headers.map{ |k,v| "#{k}: #{v}" }.join("\n") %></code></pre>
+  </section>
+<% end %>

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

@@ -2,26 +2,28 @@
   <% if Apitome.configuration.readme %>
     <li>
       <% if Apitome.configuration.single_page %>
-        <a href="#readme"><%= t(:readme) %></a>
+        <a href="#readme"><%= t(:readme, scope: :apitome) %></a>
       <% else %>
-        <a href="<%= Apitome.configuration.mount_at %>"><%= t(:readme) %></a>
+        <a href="<%= Apitome.configuration.mount_at %>"><%= t(:readme, scope: :apitome) %></a>
       <% end %>
     </li>
   <% end %>
   <% resources.each do |resource| %>
     <li>
       <% if Apitome.configuration.single_page %>
-        <a href="#<%= id_for(resource['examples'].first['link']) %>"><%= resource['name'] %></a>
+        <a href="#<%= id_for(resource['name']) %>"><%= resource['name'] %></a>
         <ul class="nav">
           <% resource['examples'].each do |example| %>
             <li><%= link_to example['description'], "##{id_for(example['link'])}" %></li>
           <% end %>
         </ul>
       <% else %>
-        <li><%= link_to resource['name'], "#{Apitome.configuration.mount_at}/#{resource['examples'].first['link'].gsub(/\.json$/, '')}" %></li>
+        <%= link_to resource['name'], resource_link(resource), class: "#{link_active?(resource_link(resource)) ? 'active' : ''}" %>
         <ul class="nav">
           <% resource['examples'].each do |example| %>
-            <li><%= link_to example['description'], "#{Apitome.configuration.mount_at}/#{example['link'].gsub(/\.json$/, '')}" %></li>
+            <li class="<%= link_active?(example_link(example)) ? 'active' : '' %>">
+              <%= link_to example['description'], example_link(example) %>
+            </li>
           <% end %>
         </ul>
       <% end %>

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

@@ -1,22 +1,22 @@
 <section class="params">
-  <h3><%= t(:parameters) %></h3>
+  <h3><%= t(:parameters, scope: :apitome) %></h3>
   <div class="table-responsive">
     <table class="table table-bordered">
       <tr>
         <% param_headers(params).each do |title| %>
-          <th><%= title %></th>
+          <th><%= title.titlecase %></th>
         <% end %>
       </tr>
       <% params.each do |param| %>
         <tr>
           <td class="name">
             <% if param['scope'] %>
-              <%= "#{param['scope']}[#{param['name']}]" %>
+              <%= "#{format_scope(param['scope'])}[#{param['name']}]" %>
             <% else %>
               <%= param['name'] %>
             <% end %>
             <% if param['required'] %>
-              <span class="label label-danger required">required</span>
+              <span class="label label-danger required"><%= t(:required, scope: :apitome) %></span>
             <% end %>
           </td>
           <td class="description"><%= param['description'] %></td>

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

@@ -1,4 +1,4 @@
 <section class="query-parameters">
-  <h4><%= t(:query_parameters) %></h4>
+  <h4><%= t(:query_parameters, scope: :apitome) %></h4>
   <pre><%= request['request_query_parameters'].map{ |k,v| "#{k}=#{v}" }.join("\n") %></pre>
 </section>

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

@@ -0,0 +1,3 @@
+<article class="resource_explanation">
+  <%= raw rendered_markdown(explanation.strip_heredoc) %>
+</article>

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

@@ -1,5 +1,5 @@
 <section class="params">
-  <h3><%= t(:response_fields) %></h3>
+  <h3><%= t(:response_fields, scope: :apitome) %></h3>
   <div class="table-responsive">
     <table class="table table-bordered">
       <tr>
@@ -11,7 +11,7 @@
         <tr>
           <td class="name">
             <% if param['scope'] %>
-              <%= "#{param['scope']}[#{param['name']}]" %>
+              <%= "#{format_scope(param['scope'])}[#{param['name']}]" %>
             <% else %>
               <%= param['name'] %>
             <% end %>

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

@@ -1,4 +1,4 @@
 <section class="route">
-  <h4><%= t(:route) %></h4>
-  <pre><%= "#{request['request_method']} #{request['request_path']}" %></pre>
+  <h4><%= t(:route, scope: :apitome) %></h4>
+  <pre><%= "#{request["request_method"]} #{request["request_path"]}" %></pre>
 </section>

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

@@ -1,4 +1,4 @@
 <section class="status">
-  <h4><%= t(:status) %></h4>
-  <pre><code class="http"><%= request['response_status'] %></code></pre>
+  <h4><%= t(:status, scope: :apitome) %></h4>
+  <pre><code class="http"><%= request["response_status"] %></code></pre>
 </section>