Using the SwaggerJekyll DOM directly in Rails

This is still some pretty hackish code, but I wanted to see how it would
work. Needs many improvements before it is merged.

Gemfile

@@ -30,6 +30,9 @@ gem 'jquery-rails-cdn'
 gem 'jquery-rails'
 gem 'selectize-rails'
 
+gem 'rouge-rails'
+gem 'swagger_jekyll', github: "harrisj/swagger-jekyll", branch: "develop"
+
 group :test do
   gem "codeclimate-test-reporter", require: nil
   gem 'codeclimate_batch', require: nil

Gemfile.lock

@@ -9,6 +9,14 @@ GIT
       hashie
       oauth2
 
+GIT
+  remote: git://github.com/harrisj/swagger-jekyll.git
+  revision: d33932752b625a90b87657ba343b6aeedd524b50
+  branch: develop
+  specs:
+    swagger_jekyll (0.0.1)
+      hana
+
 GEM
   remote: https://rubygems.org/
   specs:
@@ -166,6 +174,7 @@ GEM
       terminal-table
     haml (4.0.7)
       tilt
+    hana (1.3.2)
     hashdiff (0.3.0)
     hashie (3.4.4)
     highline (1.7.8)
@@ -298,6 +307,11 @@ GEM
       http-cookie (>= 1.0.2, < 2.0)
       mime-types (>= 1.16, < 3.0)
       netrc (~> 0.7)
+    rouge (2.0.5)
+    rouge-rails (0.2.1)
+      actionview
+      railties
+      rouge
     rspec (3.4.0)
       rspec-core (~> 3.4.0)
       rspec-expectations (~> 3.4.0)
@@ -453,6 +467,7 @@ DEPENDENCIES
   rails-erd
   rails_12factor
   redcarpet
+  rouge-rails
   rspec-rails
   rubocop
   samwise (~> 0.4.0)
@@ -461,6 +476,7 @@ DEPENDENCIES
   shoulda-matchers
   simple_form
   sinatra
+  swagger_jekyll!
   timecop
   uglifier
   validate_url

app/controllers/pages_controller.rb

@@ -0,0 +1,10 @@
+class PagesController < ApplicationController
+  before_action :load_swagger
+
+  private
+
+  def load_swagger
+    path = Rails.root.join('public', 'api', 'v0', 'swagger.json')
+    @swagger = SwaggerJekyll::Specification.load_json(path)
+  end
+end

app/views/pages/index.html.erb

@@ -0,0 +1,70 @@
+<p>This website is home to the documentation for 18F micro-purchase API.</p>
+
+From ["Open Source Micro-purchasing: An experiment in federal acquisition"](https://18f.gsa.gov/2015/10/13/open-source-micropurchasing/):
+
+> 18F is an open-source team. We currently have hundreds of publicly available repositories, with dozens under active development. We've had numerous contributions from colleagues within government, and contributions from members of the public. But in the next few weeks, we are going to run an experiment: we want to contract for contributions. And we want to do it the 18F way.
+
+Part of contracting the 18F way is ensuring that all systems are built modularly and with APIs as capable as the human interface. The [micro-purchase platform](https://micropurchase.18f.gov) itself is no exception. This means that all data and transactions that are accessible via the web UI can be accessed by software using the API.
+
+This website is written with three types of audience-members in mind:
+
+- micro-purchase participants (e.g. vendors bidding on auctions)
+- the general public (e.g. journalists or anyone else who might want to track auctions via API)
+- 18F staff (the API contains admin functionality reserved for certain 18F staff members)
+
+### Support
+
+If you are having trouble with the API, there are several ways to get help:
+
+- File an [issue](https://github.com/18F/micropurchase/issues/new).
+- Email us at micropurchase@gsa.gov.
+
+If there's anything missing or incorrect in the API documentation, please file an [issue](https://github.com/18F/micropurchase-api-docs/issues/new).
+
+As with any 18F API, it is our goal that the micro-purchase API adhere to our [API Standards](https://github.com/18f/api-standards). Please hold us accountable to these standards.
+
+### Current Version
+
+API requests should always include a version in the URL and older versions will eventually be deprecated after new versions are introduced.
+
+The current version of the API is still in alpha.
+
+<h3>Requests</h3>
+
+All API access is over HTTPS and uses the <code>micropurchase.18f.gov<%= @swagger.base_path %></code> base URL. All data is sent and received using JSON.
+
+<h3>Parameters</h3>
+
+Some requests to view specific items (like a single auction) take the auction ID as a parameter in the request URL.
+
+For bidding, the amount to be bid is submitted as the body of a POST request. They should be encoded as JSON with the following content type in the request headers:
+
+<pre>
+  <code>
+Content-Type: application/json
+  </code>
+</pre>
+
+### Client Errors
+
+Errors will contain the appropriate HTTP status code as well as a JSON response containing an `error` key:
+
+<pre>
+  <code>
+{
+  "error": "Bid amount too high"
+}
+  </code>
+</pre>
+
+<h3>Authentication</h3>
+
+<p>Currently all authentication occurs via the GitHub API. Rather than having the micro-purchase platform generate and store API keys, GitHub Personal API Tokens act as the API key. If you have created an account on the micro-purchase platform, you are signed up to use the API. All you need to do is generate a [GitHub Personal API Token](https://github.com/blog/1509-personal-api-tokens) (with no scopes) and put it in the request headers:</p>
+
+<pre>
+  <code>
+ Api-Key: the-personal-api-token
+  </code>
+</pre>
+
+Note that many routes do not require any authentication at all. These docs will note the authentication options for each route.

app/views/pages/methods.html.erb

@@ -0,0 +1,52 @@
+<div class="usa-grid">
+<% @swagger.paths.each do |path| %>
+
+<h3><%= path.path %></h3>
+
+<% path.verbs.each do |v| %>
+<h4><%= v.verb %></h4>
+
+<p><%= v.description %></p>
+
+<% if v.sample_response %>
+<p>Example response:</p>
+
+
+<%= v.sample_response%>
+<% end %>
+
+<table>
+  <thead>
+    <tr>
+      <th>Code</th>
+      <th>Meaning</th>
+      <th>Return Type</th>
+    </tr>
+  </thead>
+  <tbody>
+    <% v.responses.each do |response| %>
+    <tr>
+      <td><%= response.code %></td>
+      <td><%= response.description %></td>
+      <td><%= response.compact_type %></td>
+    </tr>
+    <% end %>
+  </tbody>
+</table>
+
+<% end %>
+<% end %>
+
+<h3>Definitions</h3>
+
+<% @swagger.definitions.each do |definition| %>
+<h4><%= definition.name %></h4>
+
+<dl>
+  <% definition.properties.each do |property| %>
+  <dt><code><%= property.name %></code>, <em><%= property.compact_type %></em></dt>
+  <dd><strong><%= property.title %>:</strong> <%= property.description %></dd>
+  <% end %>
+</dl>
+<% end %>
+</div>

app/views/pages/test.html.erb

@@ -0,0 +1,3 @@
+<h1>Hi There!</h1>
+
+<%= @swagger.base_path %>

config/routes.rb

@@ -17,6 +17,9 @@
   get '/sign_up', to: 'sign_ups#show'
   get '/sign_in', to: 'sign_ins#show'
 
+  get '/api' => 'pages#index'
+  get '/api/doc/methods' => 'pages#methods'
+
   namespace :admin do
     resources :auctions
     resources :users, only: [:index, :show, :edit, :update]