swaggable 0.4.0

data/lib/swaggable.rb

@@ -0,0 +1,14 @@
+require 'swaggable/version'
+
+module Swaggable
+  autoload :ApiDefinition, 'swaggable/api_definition'
+  autoload :EndpointDefinition, 'swaggable/endpoint_definition'
+  autoload :ParameterDefinition, 'swaggable/parameter_definition'
+  autoload :TagDefinition, 'swaggable/tag_definition'
+  autoload :ResponseDefinition, 'swaggable/response_definition'
+  autoload :RackApp, 'swaggable/rack_app'
+  autoload :GrapeAdapter, 'swaggable/grape_adapter'
+  autoload :Swagger2Serializer, 'swaggable/swagger_2_serializer'
+  autoload :Swagger2Validator, 'swaggable/swagger_2_validator'
+  autoload :EndpointIndex, 'swaggable/endpoint_index'
+end

data/lib/swaggable/api_definition.rb

@@ -0,0 +1,52 @@
+require 'forwarding_dsl'
+require 'mini_object'
+
+module Swaggable
+  class ApiDefinition
+    include ForwardingDsl::Getsetter
+
+    getsetter(
+      :version,
+      :title,
+      :description,
+      :base_path,
+    )
+
+    def initialize &block
+      configure(&block) if block_given?
+    end
+
+    def endpoints &block
+      ForwardingDsl.run(
+        @endpoints ||= build_endpoints, 
+        &block
+      )
+    end
+
+    def tags
+      (endpoints.map(&:tags).reduce(:merge) || []).dup.freeze
+    end
+
+    def self.from_grape_api grape
+      grape_adapter.import(grape, new)
+    end
+
+    def self.grape_adapter
+      @grape_adapter ||= Swaggable::GrapeAdapter.new
+    end
+
+    def configure &block
+      ForwardingDsl.run(self, &block)
+      self
+    end
+
+    private
+
+    def build_endpoints
+      MiniObject::IndexedList.new.tap do |l|
+        l.build { EndpointDefinition.new }
+        l.key {|e| "#{e.verb.to_s.upcase} #{e.path}" }
+      end
+    end
+  end
+end

data/lib/swaggable/endpoint_definition.rb

@@ -0,0 +1,54 @@
+require 'forwarding_dsl'
+require 'mini_object'
+
+module Swaggable
+  class EndpointDefinition
+    include ForwardingDsl::Getsetter
+
+    getsetter(
+      :path,
+      :verb,
+      :description,
+      :summary,
+    )
+
+    def initialize args = {}, &block
+      args.each {|k, v| self.send("#{k}=", v) }
+      configure(&block) if block_given?
+    end
+
+    def tags
+      @tags ||= MiniObject::IndexedList.new.tap do |l|
+        l.build { TagDefinition.new }
+        l.key {|e| e.name }
+      end
+    end
+
+    def parameters
+      @parameters ||= MiniObject::IndexedList.new.tap do |l|
+        l.build { ParameterDefinition.new }
+        l.key {|e| e.name }
+      end
+    end
+
+    def responses
+      @responses ||= MiniObject::IndexedList.new.tap do |l|
+        l.build { ResponseDefinition.new }
+        l.key {|e| e.status }
+      end
+    end
+
+    def consumes
+      @consumes ||= []
+    end
+
+    def produces
+      @produces ||= []
+    end
+
+    def configure &block
+      ForwardingDsl.run(self, &block)
+      self
+    end
+  end
+end

data/lib/swaggable/grape_adapter.rb

@@ -0,0 +1,84 @@
+module Swaggable
+  class GrapeAdapter
+    def import grape, api
+      api.version = grape.version
+      api.title = grape.name
+      api.base_path = '/'
+
+      grape.routes.each do |grape_endpoint|
+        api.endpoints.add_new do |api_endpoint|
+          import_endpoint grape_endpoint, api_endpoint, grape
+        end
+      end
+
+      api
+    end
+
+    private
+
+    def extract_path grape_endpoint, grape
+      path = grape_endpoint.route_path
+      path = remove_format_from_path(path)
+      path = substitute_version_in_path(path, grape)
+      substitute_parameters_in_path(path, grape_endpoint)
+    end
+
+    def remove_format_from_path path
+      path.gsub(/\(\/{0,1}\.:format\)$/,'')
+    end
+
+    def substitute_version_in_path path, grape
+      prefix = "/#{grape.prefix.to_s}".gsub(/^\/\//,'/')
+      prefix = '' if prefix == '/'
+      path.gsub(/^#{Regexp.escape prefix}\/:version/,"#{prefix}/#{grape.version}")
+    end
+
+    def substitute_parameters_in_path path, grape_endpoint
+      path = path.dup
+
+      grape_endpoint.route_compiled.names.each do |name|
+        path.gsub!(/:#{name}/, "{#{name}}")
+      end
+
+      path
+    end
+
+    def parameter_from name, options, grape_endpoint
+      Swaggable::ParameterDefinition.new do |p|
+        options = {} if options == ''
+
+        p.name = name
+        p.type = options[:type].downcase.to_sym if options[:type]
+        p.required = options[:required]
+        p.description = options[:desc]
+        p.location = if grape_endpoint.route_compiled.names.include? name
+                       :path 
+                     else
+                       :query
+                     end
+      end
+    end
+
+    def import_endpoint grape_endpoint, api_endpoint, grape
+      api_endpoint.verb = grape_endpoint.route_method.downcase
+      api_endpoint.summary = grape_endpoint.route_description
+      api_endpoint.produces << "application/#{grape.format}" if grape.format
+      api_endpoint.path = extract_path(grape_endpoint, grape)
+
+      api_endpoint.tags.add_new do |t|
+        t.name = grape.name
+      end
+
+      grape_endpoint.route_params.each do |name, options|
+        api_endpoint.parameters << parameter_from(name, options, grape_endpoint)
+      end
+
+      (grape_endpoint.route_http_codes || []).each do |status, desc, entity|
+        api_endpoint.responses.add_new do |r|
+          r.status = status
+          r.description = desc
+        end
+      end
+    end
+  end
+end

data/lib/swaggable/parameter_definition.rb

@@ -0,0 +1,50 @@
+require 'mini_object'
+
+module Swaggable
+  class ParameterDefinition
+    include ForwardingDsl::Getsetter
+
+    getsetter(
+      :name,
+      :description,
+      :location,
+      :required,
+      :type,
+    )
+
+    def initialize args = {}
+      args.each {|k, v| self.send("#{k}=", v) }
+      yield self if block_given?
+    end
+
+    def required?
+      !!required
+    end
+
+    def location= location
+      unless valid_locations.include? location
+        raise ArgumentError.new("#{location} is not one of the valid locations: #{valid_locations.join(", ")}")
+      end
+
+      @location = location
+    end
+
+    def type= type
+      unless valid_types.include? type
+        raise ArgumentError.new("#{type} is not one of the valid types: #{valid_types.join(", ")}")
+      end
+
+      @type = type
+    end
+
+    private
+
+    def valid_locations
+      [:path, :query, :header, :body, :form, nil]
+    end
+
+    def valid_types
+      [:string, :number, :integer, :boolean, :array, :file, nil]
+    end
+  end
+end

data/lib/swaggable/rack_app.rb

@@ -0,0 +1,30 @@
+require 'json'
+
+module  Swaggable
+  class RackApp
+    attr_accessor(
+      :api_definition,
+      :serializer,
+    )
+
+    def initialize args = {}
+      args.each {|k,v| send "#{k}=", v }
+    end
+
+    def call env
+      [
+        200,
+        {'Content-Type' => 'application/json'},
+        [serializer.serialize(api_definition).to_json]
+      ]
+    end
+
+    def serializer
+      @serializer ||= Swagger2Serializer.new
+    end
+
+    def validate!
+      serializer.validate! api_definition
+    end
+  end
+end

data/lib/swaggable/response_definition.rb

@@ -0,0 +1,16 @@
+require 'forwarding_dsl'
+
+module Swaggable
+  class ResponseDefinition
+    include ForwardingDsl::Getsetter
+
+    getsetter :status
+    getsetter :description
+
+    def initialize args = {}
+      args.each {|k, v| self.send("#{k}=", v) }
+      yield self if block_given?
+    end
+  end
+end
+

data/lib/swaggable/swagger_2_serializer.rb

@@ -0,0 +1,92 @@
+module Swaggable
+  # Generates a Swagger 2 hash from an {ApiDefinition}.
+  #
+  # @example Basic usage
+  #   serializer = Swagger2Serializer.new
+  #   api_definition = ApiDefinition.new
+  #   serializer.serialize(api_definition)
+  #   # => {:swagger=>"2.0", :basePath=>nil, :info=>{:title=>nil, :description=>nil, :version=>nil}, :tags=>[], :paths=>{}}
+  #
+  class Swagger2Serializer
+    attr_accessor :tag_serializer
+
+    # Main method that given an {ApiDefinition} will return a hash to serialize
+    def serialize api
+      {
+        swagger: '2.0',
+        basePath: api.base_path,
+        info: serialize_info(api),
+        tags: api.tags.map{|t| serialize_tag t },
+        paths: serialize_endpoints(api.endpoints),
+      }
+    end
+
+    def serialize_info api
+      {
+        title: api.title.to_s,
+        version: (api.version || '0.0.0'),
+      }.
+      tap do |h|
+        h[:description] = api.description if api.description
+      end
+    end
+
+    def serialize_tag tag
+      {
+        name: tag.name,
+      }.
+      tap do |e|
+        e[:description] = tag.description if tag.description
+      end
+    end
+
+    def serialize_endpoints endpoints
+      endpoints.inject({}) do |out, endpoint|
+        out[endpoint.path] ||= {}
+        out[endpoint.path][endpoint.verb] = serialize_endpoint(endpoint)
+        out
+      end
+    end
+
+    def serialize_endpoint endpoint
+      {
+        tags: endpoint.tags.map(&:name),
+        consumes: endpoint.consumes,
+        produces: endpoint.produces,
+        parameters: endpoint.parameters.map{|p| serialize_parameter p },
+        responses: serialize_responses(endpoint.responses),
+      }.
+      tap do |e|
+        e[:summary] = endpoint.summary if endpoint.summary
+        e[:description] = endpoint.description if endpoint.description
+      end
+    end
+
+    def serialize_parameter parameter
+      p = {
+        in: parameter.location.to_s,
+        name: parameter.name,
+        required: parameter.required?,
+      }
+
+      p[:type] = parameter.type || 'string'
+      p[:description] = parameter.description if parameter.description
+      p
+    end
+
+    def serialize_responses responses
+      if responses.any?
+        responses.inject({}) do |acc, r|
+          acc[r.status] = {description: r.description}
+          acc
+        end
+      else
+        {200 => {description: 'Success'}}
+      end
+    end
+
+    def validate! api
+      Swagger2Validator.validate! serialize(api)
+    end
+  end
+end

data/lib/swaggable/swagger_2_validator.rb

@@ -0,0 +1,28 @@
+require 'json-schema'
+
+module Swaggable
+  class Swagger2Validator
+    def self.validate! swagger
+      preload_draft4
+      JSON::Validator.validate!(schema, swagger)
+    end
+
+    private
+
+    def self.schema
+      @schema = assets_dir + '/swagger-2.0-schema.json'
+    end
+
+    def self.draft4
+      @draft4 = assets_dir + '/json-schema-draft-04.json'
+    end
+
+    def self.assets_dir
+      File.dirname(__FILE__) + '/../../assets'
+    end
+
+    def self.preload_draft4
+      @draft4_preloaded ||= JSON::Validator.validate!(draft4, {})
+    end
+  end
+end

data/lib/swaggable/tag_definition.rb

@@ -0,0 +1,27 @@
+require 'forwarding_dsl'
+
+module Swaggable
+  class TagDefinition
+    include ForwardingDsl::Getsetter
+
+    getsetter(
+      :name,
+      :description,
+    )
+
+    def initialize args = {}
+      args.each {|k, v| self.send("#{k}=", v) }
+      yield self if block_given?
+    end
+
+    def == other
+      self.name == other.name if other.respond_to?(:name)
+    end
+    alias eql? ==
+
+    def hash
+      name.hash
+    end
+  end
+end
+