RubyGems - doc_my_routes - Versions diffs - 0.9.0 - Mend

doc_my_routes 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

checksums.yaml +7 -0
data/etc/css/base.css +285 -0
data/etc/index.html.erb +164 -0
data/lib/doc_my_routes.rb +23 -0
data/lib/doc_my_routes/doc/config.rb +48 -0
data/lib/doc_my_routes/doc/documentation.rb +69 -0
data/lib/doc_my_routes/doc/errors.rb +6 -0
data/lib/doc_my_routes/doc/examples_handler.rb +74 -0
data/lib/doc_my_routes/doc/mapping.rb +124 -0
data/lib/doc_my_routes/doc/mixins/annotatable.rb +119 -0
data/lib/doc_my_routes/doc/route.rb +72 -0
data/lib/doc_my_routes/doc/route_collection.rb +28 -0
data/lib/doc_my_routes/doc/route_documentation.rb +78 -0
data/lib/doc_my_routes/doc/status_code_info.rb +23 -0
data/lib/doc_my_routes/version.rb +4 -0
metadata +142 -0

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bbc3ad0bfc94aa4b5af5ecd1560fb6b2ba7e6e8a
+  data.tar.gz: 2bd15f0a53ac2ae5f0c0377dd409ec286bebf29a
+SHA512:
+  metadata.gz: 5c9de394718c92d0c895274b492b837a6c337b66ddd372cd93b66bbbd494d4adae634c7ef1c5aaca2221fae2c1f71855044541f3ea48014135d9da69e987a0ba
+  data.tar.gz: 5ba49d62f21405d10a9be69a7bf071bed33f7d5e32bf498a6e3208d960f4eff0c05634a6e9aa4f2d54d7966ca8c00e084e236c32fd7931d86f8444e637b6d9ec

data/etc/css/base.css ADDED Viewed

@@ -0,0 +1,285 @@
+/* Hide focus highlightning */
+:focus
+{
+  outline:0;
+}
+body
+{
+  font-family:Verdana, Geneva, sans-serif;
+  font-size:13px;
+}
+/* Control the title and description sections */
+header
+{
+  border-bottom:1px solid #eee;
+  font-size:1.2em;
+  margin-bottom:1em;
+  padding-bottom:1em;
+}
+.info_title
+{
+  font-size:1.2em;
+  font-weight:700;
+  padding:0 0 .5em;
+}
+section.documentation
+{
+  padding:1em 10%;
+  width:70%;
+}
+section.resources
+{
+  padding:0 0 0 1em;
+}
+article.resource
+{
+  border-bottom:1px solid #eee;
+  display:block;
+  margin:0 0 .8em;
+  padding-left:0;
+}
+article.operation
+{
+  margin:.8em 0 .8em 1em;
+}
+article.operation.http_method
+{
+  text-transform:uppercase;
+}
+article.operation.get
+{
+  background-color:#e7f0f7;
+  border:1px solid #c3d9ec;
+  color:#337ab7;
+}
+article.operation.delete
+{
+  background-color:#f5e8e8;
+  border:1px solid #e8c6c7;
+  color:#a41e22;
+}
+article.operation.post
+{
+  background-color:#e7f6ec;
+  border:1px solid #c3e8d1;
+  color:#10a54a;
+}
+article.operation.put
+{
+  background-color:#f9f2e9;
+  border:1px solid #f0e0ca;
+  color:#c5862b;
+}
+.content.get
+{
+  border-top:1px solid #c3d9ec;
+}
+.content.delete
+{
+  border-top:1px solid #e8c6c7;
+}
+.content.post
+{
+  border-top:1px solid #c3e8d1;
+}
+.content.put
+{
+  border-top:1px solid #f0e0ca;
+}
+span.path
+{
+  color:#000;
+}
+summary::-webkit-details-marker
+{
+  display:none;
+}
+span.http_method
+{
+  background-color:#337ab7;
+  color:#FFF;
+  display:inline-block;
+  margin-right:1em;
+  text-align: center;
+  padding:.5em;
+  width:7em;
+}
+span.http_method.get
+{
+  background-color:#337ab7;
+}
+span.http_method.delete
+{
+  background-color:#a41e22;
+}
+span.http_method.post
+{
+  background-color:#10a54a;
+}
+span.http_method.put
+{
+  background-color:#c5862b;
+}
+div.content
+{
+  line-height:1em;
+  padding:0 .5em 1em;
+}
+span.summary
+{
+  display:inline-block;
+  float:right;
+  padding:.5em;
+  text-align:right;
+}
+span.summary.get
+{
+  color:#337ab7;
+}
+span.summary.delete
+{
+  color:#a41e22;
+}
+span.summary.post
+{
+  color:#10a54a;
+}
+span.summary.put
+{
+  color:#c5862b;
+}
+.code
+{
+  padding:0 0 0 1em;
+}
+.code.get
+{
+  background-color: #D1DFEB;
+  border: 1px solid #B2C8DB;
+}
+.code.put
+{
+  background-color:#EDDBC0;
+  border:1px solid #B2C8DB;
+}
+.code.delete
+{
+  background-color:#EDD3D4;
+  border:1px solid #D99193;
+}
+.code.post
+{
+  background-color:#C9F0D9;
+  border:1px solid #A8E3BE;
+}
+/* Ensure the content remains boxed when shrinked */
+summary {
+  overflow: hidden;
+}
+summary.resource
+{
+  color:#555;
+  font-size:1.2em;
+  font-weight:400;
+}
+/* Character to prepend to list of examples */
+summary.example::before
+{
+  content:'› ';
+}
+summary.example {
+ cursor: pointer;
+}
+p
+{
+  color:#000;
+}
+td
+{
+  border-top:1px solid #eee;
+  color:#000;
+}
+table
+{
+  border-collapse:collapse;
+}
+table td
+{
+  border-top:1px solid #ccc;
+  padding:.5em .5em .5em 0;
+}
+thead
+{
+  border-bottom:1px solid #eee;
+  color:#888;
+}
+tbody
+{
+  border-top:1px solid #eee;
+}
+th,td
+{
+  padding:.4em 1em .5em 0;
+  text-align:left;
+}
+pre
+{
+  font-family:"Anonymous Pro", Menlo, Consolas, "Bitstream Vera Sans Mono", "Courier New", monospace;
+}
+article.example
+{
+  padding:0 0 .5em;
+}
+.example_content
+{
+  color:#555;
+  margin:1em;
+}

data/etc/index.html.erb ADDED Viewed

@@ -0,0 +1,164 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title><%= data[:main][:info][:title] %></title>
+  <link href='<%= DocMyRoutes.config.destination_css %>' rel='stylesheet' type='text/css'/>
+</head>
+<body>
+  <section class="documentation">
+    <header>
+      <div id="api_info" class="info">
+        <div class="info_title"><%= data[:main][:info][:title] %></div>
+        <div class="info_description"><%= data[:main][:info][:description] %></div>
+      </div>
+    </header>
+    <section class="resources">
+      <%# API documentation content %>
+      <%
+      data[:main][:apis].each do |resource_name, operations|
+      %>
+        <article class="resource">
+          <details open>
+            <summary class="resource"><%= resource_name %></summary>
+            <%
+              operations.sort_by { |route| route[:http_method] }.each do |route|
+                 verb = route[:http_method]
+            %>
+              <article class="operation <%= verb.downcase %>">
+                <details>
+                <summary class="operation">
+                  <span class="http_method <%= verb.downcase %>">
+                    <%= verb %><%= ' / HEAD' if verb == 'GET' %>
+                  </span>
+                  <span class="path <%= verb.downcase %>">
+                    <%= route[:path]%>
+                  </span>
+                  <span class="summary <%= verb.downcase %>">
+                    <%= route[:summary]%>
+                  </span>
+                </summary>
+                <div class="content <%= verb.downcase %>">
+                  <% unless route[:produces].empty? %>
+                    <h4>Content Type</h4>
+                    <p><%= route[:produces].join(', ')  %></p>
+                  <% end %>
+                  <% if route[:notes] && !route[:notes].empty? %>
+                    <h4>Implementation Notes</h4>
+                    <p><%= route[:notes] %></p>
+                  <% end %>
+                  <%# List of , if present %>
+                  <% if route[:parameters] && !route[:parameters].empty? %>
+                    <table class="smallwidth">
+                      <thead>
+                        <tr>
+                          <th>Parameter</th>
+                        </tr>
+                      </thead>
+                      <tbody class="operation-params">
+                      <% route[:parameters].each do |param| %>
+                        <tr>
+                          <td><%= param %></td>
+                        </tr>
+                      <% end %>
+                      </tbody>
+                    </table>
+                  <% end %>
+                  <%# List of possible response statuses %>
+                  <h4>Response statuses</h4>
+                  <table class="smallwidth">
+                    <thead>
+                      <tr>
+                        <th class="status_code">HTTP Status Code</th>
+                        <th class="status_code_message">Reason</th>
+                      </tr>
+                    </thead>
+                    <tbody class="operation-status">
+                      <% route[:status_codes].each do |status_code, description| %>
+                        <tr>
+                          <td class="status_code"><%= status_code %></td>
+                          <td class="status_code_message"><%= description %></td>
+                        </tr>
+                      <% end %>
+                    </tbody>
+                  </table>
+                  <%# Display examples, if present %>
+                  <% if route[:examples] %>
+                    <h4>Examples</h4>
+                    <div>
+                      <%# TODO: move this logic outside %>
+                      <% route[:examples].each do |example| %>
+                        <article class="example <%= verb.downcase %>">
+                          <details>
+                            <summary class="example <%= verb.downcase %>"><%= example['description'] %></summary>
+                            <div class="example_content <%= verb.downcase %>">
+                              <div class="request">
+                                <h4>Request</h4>
+                                <div class="code <%= verb.downcase %>">
+                                  <div>
+                                    <h5>Query</h5>
+                                    <pre class='request-code query'><code class="json"><%= example['request']['query'] %></code></pre>
+                                  </div>
+                                  <% if example['request']['headers'] %>
+                                    <div>
+                                      <h5>Headers</h5>
+                                      <% example['request']['headers'].each do |key, value| %>
+                                        <pre class="request-code headers"><code class="json"><%= key %>: <%= value %></code></pre>
+                                      <% end %>
+                                    </div>
+                                  <% end %>
+                                  <% if example['request']['body'] %>
+                                    <div>
+                                      <h5>Body</h5>
+                                      <pre class='request-code body'><code class="json"><%= example['request']['body'] %></code></pre>
+                                    </div>
+                                  <% end %>
+                                </div>
+                              </div>
+                              <div class="response">
+                                <h4>Response (status <%= example['response']['status'] %>)</h4>
+                                <div class="code <%= verb.downcase %>">
+                                  <% if example['response']['headers'] %>
+                                    <div>
+                                      <h5>Headers</h5>
+                                      <% example['response']['headers'].each do |key, value| %>
+                                        <pre class="request-code headers"><code class="json"><%= key %>: <%= value %></code></pre>
+                                      <% end %>
+                                    </div>
+                                  <% end %>
+                                  <div>
+                                    <h5>Body</h5>
+                                    <% if example['response']['body'] %>
+                                      <pre class='request-code body'><code class="json"><%= example['response']['body'] %></code></pre>
+                                    <% else %>
+                                      <pre class='request-code body'><code class="json">No body</code></pre>
+                                    <% end %>
+                                  </div>
+                                </div>
+                              </div>
+                            </div>
+                          </details>
+                        </article>
+                      <% end %>
+                    </div>
+                  <% end %>
+                </div>
+                </details>
+              </article>
+            <% end %>
+          </details>
+        </article>
+      <% end %>
+    </section>
+  </section>
+</body>
+</html>

data/lib/doc_my_routes.rb ADDED Viewed

@@ -0,0 +1,23 @@
+require 'doc_my_routes/version'
+require 'doc_my_routes/doc/errors'
+require 'doc_my_routes/doc/documentation'
+require 'doc_my_routes/doc/config'
+require 'doc_my_routes/doc/mixins/annotatable'
+# General module that defines the base access to DocMyRoutes
+module DocMyRoutes
+  class << self
+    # Expose logging hook
+    attr_writer :logger
+    attr_accessor :config
+    def logger
+      @logger ||= begin
+        require 'logger'
+        Logger.new($stdout).tap do |log|
+          log.progname = name
+        end
+      end
+    end
+  end
+end

data/lib/doc_my_routes/doc/config.rb ADDED Viewed

@@ -0,0 +1,48 @@
+# Expose config hook
+module DocMyRoutes
+  class << self
+    attr_accessor :config
+    # Nothing fancy here, just gem configuration inspired by many gems
+    # e.g., https://robots.thoughtbot.com/mygem-configure-block
+    def configure
+      self.config ||= Config.new
+      yield(config)
+    end
+    # Inner class to maintain configuration settings
+    class Config
+      attr_accessor :title, # Project title
+                    :description, # Project description
+                    :destination_dir, # Where to store the documentation
+                    :css_file_path, # Path to look for a CSS file
+                    :examples_path_regexp # Path regexp to example files
+      attr_reader :index_template_file # Template used for the index.html
+      def initialize
+        @title = @description = @examples_path_regexp = nil
+        @destination_dir = File.join(Dir.pwd, 'doc', 'api')
+        default_static_path = File.join(File.dirname(__FILE__), '..', '..',
+                                        '..', 'etc')
+        @css_file_path = File.join(default_static_path, 'css', 'base.css')
+        @index_template_file = File.join(default_static_path, 'index.html.erb')
+      end
+      def examples
+        @examples_path_regexp.nil? ? [] : Dir.glob(@examples_path_regexp)
+      end
+      # Calculate the relative path of the CSS used
+      def destination_css
+        # TODO: make it more robust
+        File.basename(@css_file_path)
+      end
+      def index_file
+        File.join(@destination_dir, 'index.html')
+      end
+    end
+  end
+end

data/lib/doc_my_routes/doc/documentation.rb ADDED Viewed

@@ -0,0 +1,69 @@
+require_relative 'status_code_info'
+require_relative 'examples_handler'
+require_relative '../version'
+require 'ostruct'
+module DocMyRoutes
+  # class which contains the main functions to generate documentation
+  class Documentation
+    attr_reader :routes
+    def self.generate
+      Documentation.new(RouteCollection.routes, DocMyRoutes.config).generate
+    end
+    def initialize(routes, config)
+      @routes = routes
+      @config = config
+    end
+    def generate
+      generate_content
+      generate_html
+      copy_css_files
+    end
+    private
+    def resource_name(resource)
+      resource.to_s.split('::').last.downcase
+    end
+    def generate_content
+      routes.each do |resource, rts|
+        content[:main][:apis][resource_name(resource)] = rts.map(&:to_hash)
+      end
+    end
+    def copy_css_files
+      FileUtils.cp_r(@config.css_file_path,
+                     @config.destination_dir)
+    end
+    def content
+      # Set the content initial structure and default values
+      @content ||= {
+        main: {
+          apiVersion: VERSION,
+          info: {
+            title: @config.title,
+            description: @config.description
+          },
+          apis: {}
+        }
+      }
+    end
+    def generate_html
+      doc_binding = OpenStruct.new(data: content)
+                              .instance_eval { binding }
+      index_file = @config.index_file
+      File.open(index_file, 'w') do |f|
+        template_file = File.read(@config.index_template_file)
+        content = ERB.new(template_file, 0, '<>').result(doc_binding)
+        f.write content
+      end
+      DocMyRoutes.logger.info "Generated HTML file to #{index_file}"
+    end
+  end
+end

data/lib/doc_my_routes/doc/errors.rb ADDED Viewed

@@ -0,0 +1,6 @@
+# Define error classes
+module DocMyRoutes
+  class ExampleMissing < StandardError; end
+  class UnsupportedError < StandardError; end
+  class MultipleMappingDetected < UnsupportedError; end
+end

data/lib/doc_my_routes/doc/examples_handler.rb ADDED Viewed

@@ -0,0 +1,74 @@
+# Encoding: UTF-8
+module DocMyRoutes
+  # Base class to parse examples
+  #
+  # Examples are expected to be in YAML format, see README.md for details
+  class ExamplesHandler
+    class << self
+      # Load json examples generated by tests
+      def routes_examples
+        @routes_examples ||= begin
+          examples = {}
+          DocMyRoutes.config.examples.each do |example_file|
+            data = parse_example(example_file)
+            (examples[data['name']] ||= []) << data
+          end
+          examples
+        end
+      end
+      def parse_example(example_file)
+        data = YAML.load_file(example_file)
+        # Validate that mandatory parameters are present
+        fail_unless_present(%w(name description request response action),
+                            data)
+        {
+          'name' => data['name'],
+          'description' => data['description'],
+          'request' => parse_request(data),
+          'response' => parse_response(data)
+        }
+      end
+      private
+      def fail_unless_present(*fields, data)
+        fields.flatten.each do |field|
+          fail "An example doesn't have the required field #{field}: #{data}" \
+            unless data[field]
+        end
+      end
+      def parse_request(data)
+        request = {}
+        request['query'] = "#{data['action']}"
+        request['query'] += "?#{data['request']['params']}" \
+                                unless data['request']['params'].empty?
+        request['headers'] = data['request']['headers'] \
+                                unless data['request']['headers'].empty?
+        request['body'] = data['request']['body'] \
+                                if data['request']['body']
+        request
+      end
+      def parse_response(data)
+        data_response = data['response']
+        fail_unless_present(%w(headers status), data_response)
+        response = {}
+        response['body'] = data_response['body'] \
+                                unless data_response['body'].empty?
+        response['headers'] = data_response['headers']
+        response['status'] = data_response['status']
+        response
+      end
+    end
+  end
+end

data/lib/doc_my_routes/doc/mapping.rb ADDED Viewed

@@ -0,0 +1,124 @@
+# encoding: utf-8
+module DocMyRoutes
+  # Class that maintain information about the route mapping, as extracted
+  # from the actual application
+  #
+  # Sinatra applications define routes and can be mapped on different
+  # namespaces as happens with normal Rack applications.
+  #
+  # That means that given an application A that provides:
+  #   - GET /my_route
+  #
+  # its actual route might become /my_application/my_route using for instance:
+  #
+  # Rack::Builder.app do
+  #   run Rack::URLMap.new ('my_application' => A)
+  # end
+  class Mapping
+    class << self
+      attr_reader :route_mapping
+      def extract_mapping(mapping)
+        @route_mapping = {}
+        mapping.each do |_, location, _, app|
+          klass = app.class
+          klass = app.instance_variable_get('@instance').class \
+            if klass == Sinatra::Wrapper
+          (@route_mapping[klass.to_s] ||= []) << location
+        end
+        assign_namespace
+      end
+      def mapping_used?
+        Object.const_defined?('Rack::URLMap')
+      end
+      # This method associates to each route its namespace, if detected.
+      #
+      # Note: when application A is inherited by B and only B is mapped, from
+      # the point of view of the mapping only B is defined.
+      #
+      # Technically speaking, this is absolutely correct because B is the
+      # actual application that's registered and used (B provides A's methods).
+      #
+      # This method duplicates routes for applications that are not mapped in
+      # order to list their routes among the ones of the resources that
+      # inherit from them
+      def assign_namespace
+        RouteCollection.routes.each do |class_name, app_routes|
+          # TODO: deal with multiple locations for multi mapping
+          if route_mapping.include?(class_name)
+            app_routes.each do |route|
+              route.namespace = @route_mapping[class_name].first
+            end
+          else
+            remap_resource(class_name)
+          end
+        end
+      end
+      def remapped_applications
+        @remapped_applications ||= Hash.new { |hash, key| hash[key] = [] }
+      end
+      def remap_resource(class_name)
+        DocMyRoutes.logger.debug 'Remapping routes for not mapped ' \
+                                 "resource #{class_name}"
+        find_child_apps(class_name).each do |child, location|
+          DocMyRoutes.logger.debug " - Remapping to #{child}"
+          remapped_applications[class_name] << child
+          RouteCollection.routes[class_name].each do |route|
+            # TODO: If an application has multiple namespaces, we should
+            # keep a list of aliases
+            route.namespace = location.first
+          end
+        end
+      end
+      # Returns the mapped application(s) that inherited from a given class
+      def find_child_apps(class_name)
+        klass = Object.const_get(class_name)
+        route_mapping.select do |mapped_app, _|
+          Object.const_get(mapped_app).ancestors.include?(klass)
+        end
+      end
+      def mount_point_for_resource(resource)
+        class_name = resource.to_s
+        unless route_mapping
+          DocMyRoutes.logger.debug 'URLMap not used for resource ' \
+                                   "#{class_name}, assuming it's not namespaced"
+          return '/'
+        end
+        # TODO: support multiple application inheriting
+        class_name = remapped_applications[class_name].first if \
+          remapped_applications.key?(class_name)
+        locations = route_mapping[class_name]
+        validate_locations(class_name, locations)
+      end
+      # Detects if multiple locations are available and for now fail
+      def validate_locations(resource, locations)
+        fail "Resource #{resource} has multiple mappings, but that's not " \
+              "supported yet: #{locations}" if locations.size > 1
+        return locations.first if locations.size == 1
+        DocMyRoutes.logger.debug 'Unable to extract mapping for resource ' \
+                                 "#{resource}, it's not mapped! This is not " \
+                                 'necessarily a bug and might happen ' \
+                                 "because #{resource} is inherited and its " \
+                                 'children are mapped.'
+        nil
+      end
+    end
+  end
+end

data/lib/doc_my_routes/doc/mixins/annotatable.rb ADDED Viewed

@@ -0,0 +1,119 @@
+# Encoding: UTF-8
+require_relative '../route_collection'
+require_relative '../route_documentation'
+require_relative '../mapping'
+module DocMyRoutes
+  # Logic to help with the REST API documentation.
+  # This module provides methods to "decorate" sinatra routes as follows:
+  #   summary 'Short definition of the route'
+  #   notes 'More detailed explanation of the operation'
+  #   status_codes [200, 401, 500]
+  #   get '/api/example' do
+  #   end
+  module Annotatable
+    class << self
+      # When a class is extended with this module documentation specific
+      # features are enabled
+      def extended(mod)
+        # Wrap sinatra's route method to register the defined routes
+        mod.define_singleton_method(:route) do
+                                |verb, route_pattern, conditions = {}, &block|
+          result = super(verb, route_pattern, conditions, &block)
+          track_route(self, verb, route_pattern, conditions)
+          result
+        end
+        extract_url_map if Mapping.mapping_used?
+      end
+      private
+      # Wrap Rack::URLMap to extract the actual mapping when URLMap is used
+      def extract_url_map
+        DocMyRoutes.logger.debug 'Wrapping Rack::URLMap to extract mapping'
+        Rack::URLMap.send(:define_method, :initialize) do |map = {}|
+          mapping = remap(map)
+          fail 'Used Rack::URLMap, but unable to get a mapping' unless mapping
+          # Extract mapping for every class
+          #
+          # Note that the same app could be mapped to different endpoints,
+          # that's why the mapping is instance -> [location...]
+          DocMyRoutes::Mapping.extract_mapping(mapping)
+          mapping
+        end
+      end
+    end
+    def route_documentation
+      @route_documentation ||= begin
+        DocMyRoutes.logger.debug 'Tracking new route'
+        RouteDocumentation.new
+      end
+    end
+    def no_doc
+      route_documentation.hidden = true
+    end
+    def produces(*value)
+      route_documentation.produces = value
+    end
+    def summary(value)
+      route_documentation.summary = value
+    end
+    def notes(value)
+      route_documentation.notes = value
+    end
+    def status_codes(value)
+      route_documentation.status_codes = value
+    end
+    # Match interaction examples to this route
+    def examples_regex(value)
+      route_documentation.examples_regex = value
+    end
+    # It's possible to provide the route notes using a file to avoid adding
+    # too much text in the route definition
+    def notes_ref(value)
+      route_documentation.notes_ref = value
+    end
+    private
+    def track_route(resource, verb, route_pattern, conditions)
+      unless route_documentation.hidden? || skip_route(verb)
+        route = Route.new(resource, verb, route_pattern, conditions,
+                          route_documentation)
+        DocMyRoutes::RouteCollection << route
+      end
+      # Ensure values are reset
+      reset_doc_values
+    end
+    # The summary, notes and status codes are only valid for one route
+    # therefore they should be reset before the next route is processed
+    def reset_doc_values
+      @route_documentation = nil
+      @skip_route = false
+    end
+    # Sinatra duplicates the GET route creating an extra HEAD route
+    # The HEAD route is often not decorated with summary, notes and status code
+    # so this method gets those values from the previously defined GET route
+    def skip_route(verb)
+      verb == 'HEAD' && !route_documentation.present?
+    end
+  end
+end

data/lib/doc_my_routes/doc/route.rb ADDED Viewed

@@ -0,0 +1,72 @@
+# encoding: utf-8
+require 'forwardable'
+module DocMyRoutes
+  # Simple object representing a route
+  class Route
+    extend Forwardable
+    attr_accessor :resource, :verb, :route_pattern, :conditions
+    attr_reader :namespace, :documentation
+    def_delegators :documentation, :has_docs?
+    def initialize(resource, verb, route_pattern, conditions, documentation)
+      @resource = resource
+      @verb = verb
+      @route_pattern = route_pattern
+      # TODO: We could inherit this from the application mapping
+      @namespace = nil
+      @conditions = conditions
+      @documentation = documentation
+    end
+    def to_hash
+      {
+        http_method: verb,
+        parameters: param_info,
+        path: path
+      }.merge(documentation.to_hash)
+    end
+    def path
+      @path ||= begin
+        path = Mapping.mount_point_for_resource(resource) + route_pattern
+        # Changing double slashes into single slash
+        # Removing the trailing ?
+        # Removing the trailing / only if it's not the only character
+        # FROM /api/nodes/:id/?      TO      /api/nodes/:id
+        # Change the path variable from Ruby style into brackets style
+        # from /api/nodes/:id/       TO       /api/nodes/{id}/
+        path.gsub(%r{//}, '/')
+            .gsub(/(\?+)*$/, '')
+            .gsub(%r{(.+)\/$}, '\\1')
+            .gsub(/:(?<path_var>\w+)/, '{\k<path_var>}')
+      end
+    end
+    def namespace=(value)
+      fail MultipleMappingDetected, "Multiple namespaces detected for #{self}"\
+          'and not supported yet' if namespace && value != namespace
+      @namespace = value
+    end
+    def to_s
+      "#{verb} #{namespace}#{route_pattern} #{conditions}"
+    end
+    # Return a list of parameters required by this route, if specified.
+    #
+    # Try to extract parameters from the route definition otherwise
+    def param_info
+      if conditions[:parameters]
+        conditions[:parameters]
+      else
+        route_pattern.split('/').map do |part|
+          part.start_with?(':') ? part[1..-1].to_sym : nil
+        end.compact
+      end
+    end
+  end
+end

data/lib/doc_my_routes/doc/route_collection.rb ADDED Viewed

@@ -0,0 +1,28 @@
+# encoding: utf-8
+require_relative 'route'
+require_relative 'documentation'
+module DocMyRoutes
+  # Simple object representing all the sinatra routes
+  class RouteCollection
+    class << self
+      def routes
+        @routes ||= {}
+      end
+      def <<(route)
+        (routes[route.resource.to_s] ||= []) << route
+      end
+      def log_routes
+        routes.sort_by { |name, _| name }.each do |app_name, app_routes|
+          # TODO: move namespace on app?
+          namespace = format('%-50s', app_routes.first.namespace)
+          DocMyRoutes.logger.debug "Adding route to #{namespace} - #{app_name}"
+          app_routes.each { |rte| logger.debug " - #{rte}" }
+        end
+      end
+    end
+  end
+end

data/lib/doc_my_routes/doc/route_documentation.rb ADDED Viewed

@@ -0,0 +1,78 @@
+module DocMyRoutes
+  # Class holding documentation information about a given route
+  class RouteDocumentation
+    attr_accessor :summary, :notes, :status_codes, :examples_regex, :hidden,
+                  :produces, :notes_ref
+    attr_reader :examples
+    def initialize
+      @status_codes = { 200 => DocMyRoutes::StatusCodeInfo::STATUS_CODES[200] }
+      @hidden = false
+      @produces = []
+    end
+    # A route documentation object MUST have a summary, otherwise is not
+    # considered documented
+    def present?
+      !summary.nil?
+    end
+    def to_hash
+      {
+        summary: summary,
+        notes: notes,
+        status_codes: status_codes,
+        examples_regex: examples_regex,
+        produces: produces,
+        examples: examples,
+        hidden: hidden?
+      }
+    end
+    def produces=(values)
+      @produces = values.flatten.compact
+    end
+    def status_codes=(route_status_codes)
+      @status_codes = Hash[route_status_codes.map do |code|
+        [code, DocMyRoutes::StatusCodeInfo::STATUS_CODES[code]]
+      end]
+    end
+    def examples
+      @example ||= begin
+        return unless @examples_regex
+        examples = ExamplesHandler.routes_examples.values.flatten
+        examples = examples.select { |ex| ex['name'] =~ @examples_regex }
+        fail ExampleMissing, 'Unable to find examples matching regexp: ' \
+                              "#{@examples_regex} for  route '#{summary}'" \
+                                if examples.empty?
+        examples.flatten
+      end
+    end
+    # Match available examples to the filter for the current route
+    def examples_regex=(value)
+      @examples_regex = Regexp.new(value)
+    end
+    def notes
+      @notes ||= begin
+        return unless @notes_ref
+        expanded_path = File.expand_path(@notes_ref)
+        fail ScriptError, "Notes file not found: #{@notes_ref}" \
+          if @notes_ref.nil? || !File.exist?(expanded_path)
+        notes_content = File.read(expanded_path)
+        notes_content.gsub(/\n/, ' ')
+      end
+    end
+    def hidden?
+      !!@hidden
+    end
+  end
+end

data/lib/doc_my_routes/doc/status_code_info.rb ADDED Viewed

@@ -0,0 +1,23 @@
+# encoding: UTF-8
+module DocMyRoutes
+  # Mapping from HTTP status codes to human readable description
+  module StatusCodeInfo
+    STATUS_CODES = {
+      200 => 'OK',
+      201 => 'Created',
+      202 => 'Accepted',
+      204 => 'No Content',
+      303 => 'See Other',
+      304 => 'Not modified',
+      400 => 'Bad Request',
+      401 => 'Unauthorized',
+      403 => 'Forbidden',
+      404 => 'Not Found',
+      410 => 'Gone',
+      409 => 'Conflict',
+      500 => 'Internal Server Error',
+      503 => 'Service Unavailable'
+    }
+  end
+end

data/lib/doc_my_routes/version.rb ADDED Viewed

@@ -0,0 +1,4 @@
+# DocMyRoutes version
+module DocMyRoutes
+  VERSION = '0.9.0'
+end

metadata ADDED Viewed

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: doc_my_routes
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+platform: ruby
+authors:
+- Workday, Ltd.
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2015-11-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.2
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: DocMyRoutes provides a way to annotate Sinatra routes and generate documentation
+email:
+- prd.eng.os@workday.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- etc/css/base.css
+- etc/index.html.erb
+- lib/doc_my_routes.rb
+- lib/doc_my_routes/doc/config.rb
+- lib/doc_my_routes/doc/documentation.rb
+- lib/doc_my_routes/doc/errors.rb
+- lib/doc_my_routes/doc/examples_handler.rb
+- lib/doc_my_routes/doc/mapping.rb
+- lib/doc_my_routes/doc/mixins/annotatable.rb
+- lib/doc_my_routes/doc/route.rb
+- lib/doc_my_routes/doc/route_collection.rb
+- lib/doc_my_routes/doc/route_documentation.rb
+- lib/doc_my_routes/doc/status_code_info.rb
+- lib/doc_my_routes/version.rb
+homepage: https://github.com/Workday/doc_my_routes
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project:
+rubygems_version: 2.4.8
+signing_key:
+specification_version: 4
+summary: A simple gem to document Sinatra routes
+test_files: []