apipony 0.0.4 → 0.0.7

data/app/views/apipony/application/_attribute.html.erb

@@ -0,0 +1,42 @@
+<li class="attribute-container">
+  <div class="attribute">
+    <div class="attribute-name name">
+      <%= attribute.name %>
+    </div>
+
+    <div class="attribute-type type">
+      <% if attribute.is_subtype? %>
+        <%= link_to root_path(:anchor => "subtype-#{attribute.type}") do %>
+          <%= attribute.type %>
+        <% end %>
+      <% else %>
+        <%= attribute.type %>
+      <% end %>
+    </div>
+
+    <% if attribute.description %>
+      <div class="attribute-description"><%= attribute.description %></div>
+    <% end %>
+  </div>
+  
+  <% if attribute.is_enum? %>
+    <ul class="attribute-enum-list">
+      <div class="title">Possible values</div>
+      <% attribute.choices.each do |choice| %>
+        <li class="attribute-enum-member">
+          <div class="attribute-enum-member-name"><%= choice.name %></div>
+          <div class="attribute-enum-member-description"><%= choice.description %></div>
+        </li>
+      <% end %>
+    </ul>
+  <% end %>
+
+  <% if attribute.is_object? %>
+    <ul class="attribute-object-list">
+      <div class="title">Child attributes</div>
+      <%= render partial: "attribute",
+      collection: attribute.attributes,
+      as: :attribute %>
+    </ul>
+  <% end %>
+</li>

data/app/views/apipony/application/_footer.html.erb

@@ -0,0 +1,8 @@
+<footer>
+  <div class="container">
+    Powered by 
+    <%= link_to 'https://github.com/droptheplot/apipony' do %>
+      <i class="fa fa-github"></i> Apipony
+    <% end %>
+  </div>
+</footer>

data/app/views/apipony/application/_header.html.erb

@@ -0,0 +1,8 @@
+<header>
+  <div class="container">
+    <%= link_to @documentation.title, root_path, class: 'title' %>
+    <% if main_app.root_path %>
+      <%= link_to 'Back to site', main_app.root_path, class: 'back' %>
+    <% end %>
+  </div>
+</header>

data/app/views/apipony/application/_method.html.erb

@@ -0,0 +1 @@
+<span class="method <%= endpoint.method %>"><%= endpoint.method %></span><%= endpoint.url %>

data/app/views/apipony/application/_request.html.erb

@@ -0,0 +1,37 @@
+<div class="request">
+  <h4>Request&#58;</h4>
+  <% if endpoint.request.params %>
+    <div class="panel">
+      <div class="title">Parameters</div>
+      <table class="table">
+        <% endpoint.request.params.each do |param| %>
+          <tr class="parameters">
+            <td class="name">
+              <%= param.name %>
+            </td>
+            <td class="type">
+              <%= param.type %>
+            </td>
+            <td class="required">
+              <% if param.required %>
+                <i class="fa fa-check-square-o" title="Required"></i>
+              <% else %>
+                <i class="fa fa-square-o" title="Optional"></i>
+              <% end %>
+            </td>
+            <td class="example">
+              <%= param.example %>
+            </td>
+          </tr>
+        <% end %>
+      </table>
+    </div>
+  <% end %>
+
+  <% if endpoint.request.headers %>
+    <div class="panel">
+      <div class="title">Headers</div>
+      <pre class="code"><%= JSON.pretty_generate(endpoint.request.headers) %></pre>
+    </div>
+  <% end %>
+</div>

data/app/views/apipony/application/_response.html.erb

@@ -0,0 +1,30 @@
+<div class="response">
+  <h4>Response: <%= response.status %></h4>
+  <% if response.example %>
+    <div class="response-example">
+      <%# This is kind of fancy for no reason but whatever %>
+      <% if response.example.headers %>
+        <div class="title">Headers</div>
+        <pre class="code hljs json"><%= JSON.pretty_generate(response.example.headers) %></pre>
+      <% end %>
+
+      <% if response.example.body %>
+        <div class="panel">
+          <div class="title">Body</div>
+          <pre class="code hljs json"><%= JSON.pretty_generate(response.example.body) %></pre>
+        </div>
+      <% end %>
+    </div>
+  <% end %>
+
+  <% if response.attributes.size > 0 %>
+    <div class="panel">
+      <div class="title">Attributes</div>
+      <div class="table">
+        <div class="attributes">
+          <%= render partial: 'attribute', collection: response.attributes, as: :attribute %>
+        </div>
+      </div>
+    </div>
+  <% end %>
+</div>

data/app/views/apipony/application/_sidebar.html.erb

@@ -0,0 +1,16 @@
+<% @documentation.sections.each do |section| %>
+  <h4>
+    <%= link_to section.title, root_path(:anchor => section.title) %>
+  </h4>
+  <ul>
+    <% section.endpoints.each do |endpoint| %>
+      <li>
+        <h5>
+          <%= link_to root_path(:anchor => endpoint.id) do %>
+            <span class="method <%= endpoint.method %>"><%= endpoint.method %></span><%= endpoint.url %>
+          <% end %>
+        </h5>
+      </li>
+    <% end %>
+  </ul>
+<% end %>

data/app/views/apipony/application/index.html.erb

@@ -0,0 +1,60 @@
+<%= render partial: "header" %>
+
+<main>
+  <div class="container">
+    <div class="row">
+      <div class="sidebar">
+        <%= render partial: "sidebar" %>
+      </div>
+
+      <div class="main-col">
+        <% @documentation.sections.each do |section| %>
+          <div class="section">
+            <h2 id="<%= section.title %>"><%= section.title %></h2>
+            <% section.endpoints.each do |endpoint| %>
+              <div class="endpoint" id="<%= endpoint.id %>">
+                <h3><%= render "method", endpoint: endpoint %></h3>
+
+                <% if endpoint.description %>
+                  <div class="description">
+                    <%= endpoint.description %>
+                  </div>
+                <% end %>
+
+                <% if endpoint.request || endpoint.response %>
+                  <% if endpoint.request %>
+                    <%= render "request", endpoint: endpoint %>
+                  <% end %>
+
+                  <% if endpoint.response %>
+                    <%= render "response", response: endpoint.response %> 
+                  <% end %>
+                <% end %>
+              </div>
+            <% end %>
+          </div>
+        <% end %>
+        
+        <div id="defined_subtypes">
+          <% @documentation.subtypes.each do |name, type| %>
+            <div class="subtype" id="subtype-<%= name %>">
+              <h4><%= name %></h4>
+              <div class="panel">
+                <div class="title">Attributes</div>
+                <div class="table">
+                  <div class="attributes">
+                    <%= render partial: "attribute", 
+                    collection: type.attributes, 
+                    as: :attribute %>
+                  </div>
+                </div>
+              </div>
+            </div>
+          <% end %>
+        </div>
+      </div>
+    </div>
+  </div>
+</main>
+
+<%= render partial: "footer" %>

data/app/views/layouts/apipony/application.html.erb

@@ -0,0 +1,22 @@
+<html>
+  <head>
+    <%# UTF-8 Character Set %>
+    <meta charset="utf-8">
+
+    <%# HTML Title %>
+    <title><%= @documentation.title %></title>
+
+    <%# Viewport meta tag %>
+    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
+
+    <link rel='stylesheet' href='//cdnjs.cloudflare.com/ajax/libs/highlight.js/8.9.1/styles/github.min.css'>
+    <link rel='stylesheet' href='https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css'>
+    <%= stylesheet_link_tag 'apipony/application', media: 'all' %>
+    <script src='//cdnjs.cloudflare.com/ajax/libs/highlight.js/8.9.1/highlight.min.js'></script>
+    <%= javascript_include_tag 'apipony/application' %>
+    <%= csrf_meta_tags %>
+  </head>
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/lib/apipony.rb

@@ -7,6 +7,25 @@ require 'apipony/endpoint'
 require 'apipony/response'
 require 'apipony/request'
 require 'apipony/parameter'
+require 'apipony/response_attribute'
+require 'apipony/example_response'
 
 module Apipony
+
+  ##
+  # This allows you to define a common sub-type of attributes.
+  # A typical example is something like a list of users. If you want to 
+  # display all users who created an image, who subscribe to a channel, or who
+  # are in a group, it may be useful if the information on those users is in a
+  # common format. This lets you define one common format, which you can then
+  # merge in to other attributes.
+  # = Example
+  #     Apipony.define_attribute_type :user_stub do
+  #       attribute :name
+  #       attribute :id
+  #     end
+  def self.define_attribute_type(name, **params, &block)
+    a = Apipony::ResponseAttribute.new("", **params, &block)
+    Apipony::ResponseAttribute.define_type(name, a)
+  end
 end

data/lib/apipony/documentation.rb

@@ -1,3 +1,5 @@
+##
+# Top-level class for the DSL 
 class Apipony::Documentation
   class << self
     attr_accessor :title, :base_url, :sections
@@ -9,11 +11,33 @@ class Apipony::Documentation
 
       instance_eval(&block)
     end
+    ##
+    # @return [Hash<String, ApiPony::ResponseAttribute] a hash of each subype.
+    #   keys are the names of the subtype, values are the attribute object that
+    #   defines it
+    def subtypes
+      Apipony::ResponseAttribute.defined_subtypes
+    end
 
+    ##
+    # Start a new section.
+    # Sections are logically separated on the display page.
     def section(title, &block)
       @sections << Apipony::Section.new(title, &block)
     end
 
+    ##
+    # Define a new subtype.
+    # A subtype describes a common object used in various places in your Api.
+    # Once defined, setting the `type` of an attribute to this given name will
+    # cause it to reference this subtype in a common location. 
+    # @param [String] name what to call this subtype
+    def subtype(name, **params, &block)
+      Apipony.define_attribute_type(name, **params, &block)
+    end
+
+    ##
+    # Configure API pony with the DSL
     def config(&block)
       instance_eval(&block)
     end

data/lib/apipony/endpoint.rb

@@ -1,5 +1,20 @@
+##
+# Model a response endpoint.
 class Apipony::Endpoint < Apipony::Base
-  attr_accessor :method, :url, :description, :response, :request
+  ##
+  # What HTTP verb to use to access this endpoint
+  attr_accessor :method
+  ##
+  # The URl of this endpoint
+  attr_accessor :url
+
+  ##
+  # A short description of what this endpoint does and why it may be useful.
+  attr_accessor :description
+
+  ##
+  #:nodoc:
+  attr_accessor :response, :request
 
   def initialize(method, url, &block)
     @method = method
@@ -8,14 +23,20 @@ class Apipony::Endpoint < Apipony::Base
     instance_eval(&block) if block_given?
   end
 
-  def response_with(status, &block)
-    @response = Apipony::Response.new(status, &block)
+  ##
+  # DSL method to start describing a response
+  def response_with(status, **params, &block)
+    @response = Apipony::Response.new(status, **params, &block)
   end
 
+  ##
+  # DSL method to start describind a request
   def request_with(&block)
     @request = Apipony::Request.new(&block)
   end
 
+  ##
+  # Create a unique identifier for this endpoint
   def id
     File.join(@method, @url)
   end

data/lib/apipony/engine.rb

@@ -1,4 +1,6 @@
 module Apipony
+  ## 
+  # Rails engine so you can just drop Apipony right into your application
   class Engine < ::Rails::Engine
     isolate_namespace Apipony
   end

data/lib/apipony/example_response.rb

@@ -0,0 +1,9 @@
+##
+# Display an example response to help with understanding of the API.
+class Apipony::ExampleResponse < Apipony::Base
+  attr_accessor :headers, :body
+  def initialize(&block)
+    instance_eval(&block) if block_given?
+  end
+
+end

data/lib/apipony/parameter.rb

@@ -1,10 +1,11 @@
 class Apipony::Parameter < Apipony::Base
-  attr_accessor :name, :type, :example, :required
+  attr_accessor :name, :type, :example, :required, :description
 
-  def initialize(name, example, type, required)
+  def initialize(name, example, type, required, description)
     @name = name
     @example = example
     @type = type
     @required = required
+    @description = description
   end
 end

data/lib/apipony/request.rb

@@ -1,13 +1,26 @@
+##
+# Model a request that an API user can make.
+# Includes information about required parameters and required headers
 class Apipony::Request < Apipony::Base
-  attr_accessor :params, :headers
+  ##
+  # :nodoc:
+  attr_accessor :params
+  ##
+  #:nodoc:
+  attr_accessor :headers
 
   def initialize(&block)
     @params = []
 
     instance_eval(&block)
   end
-
-  def param(name, example: '', type: :string, required: false)
-    @params << Apipony::Parameter.new(name, example, type, required)
+  ##
+  # Construct a new parameter
+  def param(name, 
+            example: '', 
+            type: :string, 
+            required: false,
+            description: '')
+    @params << Apipony::Parameter.new(name, example, type, required, description)
   end
 end

data/lib/apipony/response.rb

@@ -1,9 +1,51 @@
-class Apipony::Response < Apipony::Base
-  attr_accessor :status, :headers, :body
-
-  def initialize(status, &block)
+class Apipony::Response
+  attr_accessor :example, :attributes, :status
+  def initialize(status, array: false, &block)
     @status = status
-
+    @attributes = []
+    @array = array
     instance_eval(&block) if block_given?
   end
+
+  def is_array?
+    !! @array
+  end
+
+  def example(&block)
+    if block_given?
+      @example = Apipony::ExampleResponse.new(&block)
+    else
+      find_example
+    end
+  end
+
+  def attribute(name, **params, &block)
+    if params[:example]
+      @use_attribute_examples = true
+    end
+    @attributes << Apipony::ResponseAttribute.new(name, **params, &block)
+  end
+  private
+  def find_example
+    if @use_attribute_examples
+      build_example_from_attributes
+    end
+    @example
+  end
+
+  def build_example_from_attributes
+    build = Hash.new
+    @attributes.each do |attr|
+      build[attr.name] = attr.example if attr.example
+    end
+    @example ||= Apipony::ExampleResponse.new
+    case @example.body
+    when Hash
+      @example.body.merge! build
+      @example.body = [@example.body] if is_array?
+    when NilClass
+      @example.body = (is_array? ? [build] : build)
+    end
+    @example
+  end
 end