RubyGems - doc_my_routes - Versions diffs - 0.9.0 - Mend

doc_my_routes 0.9.0

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: []