swagger_yard 0.0.5

data/lib/swagger_yard/api.rb

@@ -0,0 +1,132 @@
+module SwaggerYard
+  class Api
+    attr_reader :nickname
+    attr_accessor :path, :parameters, :description, :http_method, :response_class, :summary, :notes, :error_responses
+
+    def initialize(yard_object)
+      @description = yard_object.docstring
+      @parameters  = []
+      
+      yard_object.tags.each do |tag|
+        value = tag.text
+
+        case tag.tag_name
+        when "path"
+          parse_path(value)
+        when "parameter"
+          @parameters << parse_parameter(value)
+        when "parameter_list"
+          @parameters << parse_parameter_list(value)
+        when "summary"
+          @summary = value
+        when "notes"
+          @notes = value.gsub("\n", "<br\>")
+        end
+      end
+
+      @parameters.sort_by { |parameter| parameter["name"] }
+      @parameters << add_format_parameters
+    end
+
+    def nickname
+      @nickname ||= "#{http_method}".camelize
+    end
+
+    def operation 
+      {
+        "httpMethod"     => http_method,
+        "nickname"       => path[1..-1].gsub(/[^a-zA-Z\d:]/, '-').squeeze("-") + http_method.downcase,
+        "responseClass"  => response_class || "void",
+        "produces"       => ["application/json", "application/xml"],
+        "parameters"     => parameters,
+        "summary"        => summary || description,
+        "notes"          => notes,
+        "errorResponses" => error_responses
+      }
+    end
+
+    def to_h
+      {
+        "path"        => path,
+        "description" => description,
+        "operations"  => [operation],
+      }
+    end
+
+    def valid?
+      path.present?
+    end
+
+  private
+    ##
+    # Example: [GET] /api/v2/ownerships.{format_type}
+    def parse_path(string)
+      @http_method, @path = string.match(/^\[(\w*)\]\s*(.*)$/).captures
+
+      path_params = @path.scan(/\{([^\}]+)\}/).flatten.reject { |value| value == "format_type" }
+      
+      path_params.each do |path_param|
+        @parameters << {
+          "paramType"     => "path",
+          "name"          => path_param,
+          "description"   => "Scope response to #{path_param}",
+          "dataType"      => "string",
+          "required"      => true,
+          "allowMultiple" => false
+        }
+      end
+    end
+
+    ##
+    # Example: [Array]     status            Filter by status. (e.g. status[]=1&status[]=2&status[]=3)
+    # Example: [Array]     status(required)  Filter by status. (e.g. status[]=1&status[]=2&status[]=3)
+    # Example: [Integer]   media[media_type_id]                          ID of the desired media type.
+    def parse_parameter(string)
+      data_type, name, required, description = string.match(/\A\[(\w*)\]\s*([\w\[\]]*)(\(required\))?\s*(.*)\Z/).captures
+      allow_multiple = name.gsub!("[]", "")
+
+      parameter = {
+        "paramType"     => "query",
+        "name"          => name,
+        "description"   => description,
+        "dataType"      => data_type.downcase,
+        "required"      => required.present?,
+        "allowMultiple" => allow_multiple.present?
+      }
+    end
+
+    ##
+    # Example: [String]    sort_order  Orders ownerships by fields. (e.g. sort_order=created_at)
+    #          [List]      id              
+    #          [List]      begin_at        
+    #          [List]      end_at          
+    #          [List]      created_at      
+    def parse_parameter_list(string)
+      data_type, name, required, description, set_string = string.match(/\A\[(\w*)\]\s*(\w*)(\(required\))?\s*(.*)\n([.\s\S]*)\Z/).captures
+      
+      list_values = set_string.split("[List]").map(&:strip).reject { |string| string.empty? }
+
+      parameter = {
+        "paramType"       => "query",
+        "name"            => name,
+        "description"     => description,
+        "dataType"        => data_type.downcase,
+        "required"        => required.present?,
+        "allowMultiple"   => false,
+        "allowableValues" => {"valueType" => 'LIST', "values" => list_values}
+      }
+    end
+
+    def add_format_parameters
+      @add_format_parameters ||= {
+        "paramType"       => "path",
+        "name"            => "format_type",
+        "description"     => "Response format either JSON or XML",
+        "dataType"        => "string",
+        "required"        => true,
+        "allowMultiple"   => false,
+        "allowableValues" => {"valueType" => "LIST", "values" => ["json", "xml"]}
+      }
+    end
+  end
+end

data/lib/swagger_yard/api_declaration.rb

@@ -0,0 +1,42 @@
+module SwaggerYard
+  class ApiDeclaration
+    attr_accessor :description, :resource_path
+
+    def initialize
+      @apis   = {}
+      @models = []
+    end
+
+    def add_listing_info(yard_object)
+      @description = yard_object.docstring if yard_object.docstring.present?
+      tag = yard_object.tags.find { |tag| tag.tag_name == "resource_path"}
+      @resource_path = tag.text.downcase if tag.present?
+      tag.present?
+    end
+
+    def add_api(api)
+      if @apis.keys.include?(api.path)
+        same_api_path = @apis[api.path]
+        same_api_path["operations"] << api.operation
+        @apis[api.path] = same_api_path
+      else
+        @apis[api.path] = api.to_h
+      end 
+    end
+
+    def resource_name
+      @resource_path
+    end
+
+    def to_h
+      { 
+        "apiVersion"     => SwaggerYard.api_version,
+        "swaggerVersion" => SwaggerYard.swagger_version,
+        "basePath"       => SwaggerYard.api_base_path,
+        "resource_path"  => @resource_path,
+        "apis"           => @apis.values,
+        "models"         => @models
+      }
+    end
+  end
+end

data/lib/swagger_yard/cache.rb

@@ -0,0 +1,50 @@
+module SwaggerYard
+  # For now just a simple wrapper class for a Memcache client.
+  class Cache
+
+    attr_reader :prefix, :store
+
+    def initialize(store, prefix)
+      @store = store
+      @prefix = prefix
+    end
+
+    # Read from the Cache.
+    def [](resource_name)
+      case
+        when store.respond_to?(:read)
+          store.read key_for(resource_name)
+        when store.respond_to?(:[])
+          store[key_for(resource_name)]
+        when store.respond_to?(:get)
+          store.get key_for(resource_name)
+      end
+    end
+
+    # Write to the Cache.
+    def []=(resource_name, value)
+      case
+        when store.respond_to?(:write)
+          store.write key_for(resource_name), value
+        when store.respond_to?(:[]=)
+          store[key_for(resource_name)] = value
+        when store.respond_to?(:set)
+          store.set key_for(resource_name), value
+      end
+    end
+
+    def fetch(resource_name)
+      value = self[resource_name]
+      if value.nil? && block_given?
+        value = yield
+        self[resource_name] = yield
+      end
+      value
+    end
+
+    # Cache key for a given entry.
+    def key_for(resource_name)
+      [prefix, resource_name].join
+    end
+  end
+end

data/lib/swagger_yard/engine.rb

@@ -0,0 +1,18 @@
+require "swagger_yard/local_dispatcher"
+
+module SwaggerYard
+  class Engine < ::Rails::Engine
+    if SwaggerYard::LocalDispatcher.new.server?
+      isolate_namespace SwaggerYard
+
+      # NOTE: We should opt for asset pipeline instead of this.
+      initializer 'swagger_yard.load_static_assets' do |app|
+        app.middleware.use(::ActionDispatch::Static, "#{root}/public")
+      end
+
+      initializer "swagger_yard.finisher_hook" do |app|
+        SwaggerYard.generate!("#{app.root}/app/controllers/**/*.rb")
+      end
+    end
+  end
+end

data/lib/swagger_yard/local_dispatcher.rb

@@ -0,0 +1,51 @@
+module SwaggerYard
+  # An instance of LocalEnvironment is responsible for determining the dispatcher. 
+  # This is useful to determine whether or not to run SwaggerYard#generate!.
+  # 
+  # Implementation heavily borrowed from NewRelic.
+  class LocalDispatcher
+    def discovered_dispatcher
+      discover_dispatcher unless @discovered_dispatcher
+      @discovered_dispatcher
+    end
+
+    def server?
+      [:thin, :unicorn].include?(discovered_dispatcher)
+    end
+
+  private
+
+    def discover_dispatcher
+      dispatchers = %w[sidekiq thin unicorn]
+      while dispatchers.any? && @discovered_dispatcher.nil?
+        send 'check_for_' + (dispatchers.shift)
+      end
+    end
+
+    def find_class_in_object_space(klass)
+      ObjectSpace.each_object(klass) do |x|
+        return x
+      end
+      return nil
+    end
+
+    def check_for_unicorn
+      if defined?(::Unicorn) && defined?(::Unicorn::HttpServer)
+        v = find_class_in_object_space(::Unicorn::HttpServer)
+        @discovered_dispatcher = :unicorn if v
+      end
+    end
+
+    def check_for_sidekiq
+      if defined?(::Sidekiq) && File.basename($0) == 'sidekiq'
+        @discovered_dispatcher = :sidekiq
+      end
+    end
+
+    def check_for_thin
+      if defined?(::Thin) && defined?(::Thin::VERSION)
+        @discovered_dispatcher = :thin
+      end
+    end
+  end
+end

data/lib/swagger_yard/parameter.rb

@@ -0,0 +1,9 @@
+module SwaggerYard
+  class Parameter
+    attr_accessor :param_type, :name, :description, :data_type, :required, :allow_multiple, :allowable_values
+
+    def initialize(yard_object)
+      
+    end
+  end
+end

data/lib/swagger_yard/parser.rb

@@ -0,0 +1,35 @@
+require_relative 'api'
+require_relative 'api_declaration'
+require_relative 'resource_listing'
+
+module SwaggerYard
+  class Parser
+    attr_reader :listing
+
+    def initialize
+      @listing = ResourceListing.new
+    end
+
+    def run(yard_objects)
+      api_declaration = ApiDeclaration.new
+      retain_api = true
+      
+      yard_objects.each do |yard_object|
+        case yard_object.type
+        when :class
+          break unless retain_api = api_declaration.add_listing_info(yard_object)
+        when :method
+          api = Api.new(yard_object)
+          api_declaration.add_api(api) if api.valid?
+        end
+      end
+
+      if retain_api
+        @listing.add(api_declaration)
+        api_declaration
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/swagger_yard/resource_listing.rb

@@ -0,0 +1,32 @@
+module SwaggerYard
+  class ResourceListing
+    attr_reader :api_declarations
+
+    def initialize
+      @api_declarations = []
+    end
+
+    def add(api_declaration)
+      @api_declarations << api_declaration
+    end
+
+    def to_h
+      { 
+        "apiVersion"     => SwaggerYard.api_version,
+        "swaggerVersion" => SwaggerYard.swagger_version,
+        "basePath"       => SwaggerYard.doc_base_path,
+        "apis"           => list_api
+      }
+    end
+
+  private
+    def list_api
+      @api_declarations.map do |api_declaration|
+        {
+          "path"        => api_declaration.resource_path,
+          "description" => api_declaration.description
+        }
+      end.sort_by { |hsh| hsh["path"] }
+    end
+  end
+end

data/lib/swagger_yard/version.rb

@@ -0,0 +1,3 @@
+module SwaggerYard
+  VERSION = "0.0.5"
+end

data/public/swagger-ui/css/hightlight.default.css

@@ -0,0 +1,135 @@
+/*
+
+Original style from softwaremaniacs.org (c) Ivan Sagalaev <Maniac@SoftwareManiacs.Org>
+
+*/
+
+pre code {
+  display: block; padding: 0.5em;
+  background: #F0F0F0;
+}
+
+pre code,
+pre .subst,
+pre .tag .title,
+pre .lisp .title,
+pre .clojure .built_in,
+pre .nginx .title {
+  color: black;
+}
+
+pre .string,
+pre .title,
+pre .constant,
+pre .parent,
+pre .tag .value,
+pre .rules .value,
+pre .rules .value .number,
+pre .preprocessor,
+pre .ruby .symbol,
+pre .ruby .symbol .string,
+pre .aggregate,
+pre .template_tag,
+pre .django .variable,
+pre .smalltalk .class,
+pre .addition,
+pre .flow,
+pre .stream,
+pre .bash .variable,
+pre .apache .tag,
+pre .apache .cbracket,
+pre .tex .command,
+pre .tex .special,
+pre .erlang_repl .function_or_atom,
+pre .markdown .header {
+  color: #800;
+}
+
+pre .comment,
+pre .annotation,
+pre .template_comment,
+pre .diff .header,
+pre .chunk,
+pre .markdown .blockquote {
+  color: #888;
+}
+
+pre .number,
+pre .date,
+pre .regexp,
+pre .literal,
+pre .smalltalk .symbol,
+pre .smalltalk .char,
+pre .go .constant,
+pre .change,
+pre .markdown .bullet,
+pre .markdown .link_url {
+  color: #080;
+}
+
+pre .label,
+pre .javadoc,
+pre .ruby .string,
+pre .decorator,
+pre .filter .argument,
+pre .localvars,
+pre .array,
+pre .attr_selector,
+pre .important,
+pre .pseudo,
+pre .pi,
+pre .doctype,
+pre .deletion,
+pre .envvar,
+pre .shebang,
+pre .apache .sqbracket,
+pre .nginx .built_in,
+pre .tex .formula,
+pre .erlang_repl .reserved,
+pre .prompt,
+pre .markdown .link_label,
+pre .vhdl .attribute,
+pre .clojure .attribute,
+pre .coffeescript .property {
+  color: #88F
+}
+
+pre .keyword,
+pre .id,
+pre .phpdoc,
+pre .title,
+pre .built_in,
+pre .aggregate,
+pre .css .tag,
+pre .javadoctag,
+pre .phpdoc,
+pre .yardoctag,
+pre .smalltalk .class,
+pre .winutils,
+pre .bash .variable,
+pre .apache .tag,
+pre .go .typename,
+pre .tex .command,
+pre .markdown .strong,
+pre .request,
+pre .status {
+  font-weight: bold;
+}
+
+pre .markdown .emphasis {
+  font-style: italic;
+}
+
+pre .nginx .built_in {
+  font-weight: normal;
+}
+
+pre .coffeescript .javascript,
+pre .javascript .xml,
+pre .tex .formula,
+pre .xml .javascript,
+pre .xml .vbscript,
+pre .xml .css,
+pre .xml .cdata {
+  opacity: 0.5;
+}