Add support for custom link headers in examples

jasonrudolph · jasonrudolph · commit 4ba8d44400d1 · 2013-12-23T17:49:23.000-05:00
diff --git a/README.md b/README.md
@@ -52,7 +52,7 @@ API docs should look like:
 
     ### Response
 
-    <%= headers 200, :pagination => true, 'X-Custom-Header' => "value" %>
+    <%= headers 200, :pagination => :default, 'X-Custom-Header' => "value" %>
     <%= json :resource_name %>
 
 **Note**: We're using [Kramdown Markdown extensions](http://kramdown.rubyforge.org/syntax.html), such as definition lists.
diff --git a/content/v3/activity/events.md b/content/v3/activity/events.md
@@ -33,7 +33,7 @@ Fetching up to ten pages is supported, for a total of 300 events.
 
 All Events have the same response format:
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:event) { |h| [h] } %>
 
 ## List public events
diff --git a/content/v3/activity/starring.md b/content/v3/activity/starring.md
@@ -27,7 +27,7 @@ for more details.
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:user) { |h| [h] } %>
 
 ## List repositories being starred
@@ -50,7 +50,7 @@ Name | Type | Description
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:repo) { |h| [h] } %>
 
 ## Check if you are starring a repository
diff --git a/content/v3/activity/watching.md b/content/v3/activity/watching.md
@@ -29,7 +29,7 @@ post](/changes/2012-9-5-watcher-api/) for more details.
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:user) { |h| [h] } %>
 
 ## List repositories being watched
@@ -44,7 +44,7 @@ List repositories being watched by the authenticated user.
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:repo) { |h| [h] } %>
 
 ## Get a Repository Subscription
diff --git a/content/v3/gists.md b/content/v3/gists.md
@@ -42,7 +42,7 @@ Name | Type | Description
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:gist) { |h| [h] } %>
 
 ## Get a single gist
diff --git a/content/v3/issues.md b/content/v3/issues.md
@@ -39,7 +39,7 @@ Name | Type | Description
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:issue) { |h| [h] } %>
 
 ## List issues for a repository
@@ -62,7 +62,7 @@ Name | Type | Description
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:issue) { |h| [h] } %>
 
 ## Get a single issue
diff --git a/content/v3/issues/comments.md b/content/v3/issues/comments.md
@@ -20,7 +20,7 @@ You can read more about the use of media types in the API
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:issue_comment) { |h| [h] } %>
 
 ## List comments in a repository
diff --git a/content/v3/issues/events.md b/content/v3/issues/events.md
@@ -55,7 +55,7 @@ assigned
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:issue_event) { |h| [h] } %>
 
 ## List events for a repository
@@ -64,7 +64,7 @@ assigned
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:full_issue_event) { |h| [h] } %>
 
 ## Get a single event
diff --git a/content/v3/issues/milestones.md b/content/v3/issues/milestones.md
@@ -22,7 +22,7 @@ Name | Type | Description
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:milestone) { |h| [h] } %>
 
 ## Get a single milestone
diff --git a/content/v3/oauth.md b/content/v3/oauth.md
@@ -162,7 +162,7 @@ users have two-factor authentication enabled.)
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:oauth_access) { |h| [h] } %>
 
 ## Get a single authorization
diff --git a/content/v3/orgs.md b/content/v3/orgs.md
@@ -19,7 +19,7 @@ List public and private organizations for the authenticated user.
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:org) { |h| [h] } %>
 
 ## Get an Organization
diff --git a/content/v3/repos.md b/content/v3/repos.md
@@ -56,7 +56,7 @@ Name | Type | Description
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:repo) { |h| [h] } %>
 
 <div class="alert">
diff --git a/content/v3/repos/hooks.md b/content/v3/repos/hooks.md
@@ -92,7 +92,7 @@ The JSON HTTP API follows the same conventions as the rest of the
 
 #### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:hook) { |h| [h] } %>
 
 ### Get single hook
diff --git a/content/v3/users/followers.md b/content/v3/users/followers.md
@@ -19,7 +19,7 @@ List the authenticated user's followers:
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:user) { |h| [h] } %>
 
 ## List users followed by another user
@@ -34,7 +34,7 @@ List who the authenticated user is following:
 
 ### Response
 
-<%= headers 200, :pagination => true %>
+<%= headers 200, :pagination => :default %>
 <%= json(:user) { |h| [h] } %>
 
 ## Check if you are following a user
diff --git a/lib/resources.rb b/lib/resources.rb
@@ -68,9 +68,9 @@ def headers(status, head = {})
         head.each do |key, value|
           case key
             when :pagination
-              lines << 'Link: <https://api.github.com/resource?page=2>; rel="next",'
-              lines << '      <https://api.github.com/resource?page=5>; rel="last"'
-            else lines << "#{key}: #{value}"
+              lines << link_header(value)
+            else
+              lines << "#{key}: #{value}"
           end
         end
 
@@ -80,6 +80,30 @@ def headers(status, head = {})
         %(<pre class="#{css_class}"><code>#{lines * "\n"}</code></pre>\n)
       end
 
+      def link_header(rels)
+        rels = default_rels if rels == :default
+        formatted_rels = rels.map { |name, url| link_header_rel(name, url) }
+
+        lines = ["Link: #{formatted_rels.shift}"]
+        while formatted_rels.any?
+          lines.last << ","
+          lines << "      #{formatted_rels.shift}"
+        end
+
+        lines
+      end
+
+      def link_header_rel(name, url)
+        %Q{<#{url}>; rel="#{name}"}
+      end
+
+      def default_rels
+        {
+          :next => "https://api.github.com/resource?page=2",
+          :last => "https://api.github.com/resource?page=5"
+        }
+      end
+
       def json(key)
         hash = case key
           when Hash
