rails-swagger 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0ca0079ec6e56d59984482c58ba8f88848f0c4cf
+  data.tar.gz: 74419e6fdc5516c8f86b52791c56c7acce3b0904
+SHA512:
+  metadata.gz: 9513137bdc27e6caed663bf6a6efe819ae089be425d9b9d1eecac25a1fc00b26f37d3d84bc70aec51fa4fea51fc536cd8c763765703b82307c68f9c9ebfe6951
+  data.tar.gz: f047a592844a8cf8b44fee3ee267ac09916674295b92de1325ca30382184e0d303c74d9bfc4c15582d9cf3f903c9b1d8e9e012e8d8c1ac05bc684ee9bed6c1af

data/lib/rails/swagger/controller.rb

@@ -0,0 +1,30 @@
+module Rails
+	module Swagger
+		module Controller
+
+			# Injects swagger-related code into the controller when included
+			def self.included base
+
+				# Add controller hooks
+				base.class_eval do
+					before_action :validate_swagger_params
+				end
+
+				# Returns the swagger spec definition for the endpoint serving
+				# the current request.
+				def swagger_endpoint
+					key = "#{params[:controller]}##{params[:action]}"
+					endpoint = rails_swagger_engine.endpoints[key]
+				end
+
+				# Validates request parameters against the Swagger API spec
+				# associated with this controller.
+				def validate_swagger_params
+					#puts swagger_endpoint.inspect.white
+				end
+
+			end
+
+		end
+	end
+end

data/lib/rails/swagger/engine.rb

@@ -0,0 +1,149 @@
+module Rails
+	module Swagger
+
+		# Defines the Swagger spec file formats that are parsable by this gem.
+		# Currently only the JSON format is supported.
+		ALLOWED_FORMATS = [".json"].freeze
+
+		# Defines a base class from which Swagger API engines can be created.
+		# Uses namespace isolation to ensure routes don't conflict with any
+		# pre-existing routes from the main rails application.
+		class Engine < Rails::Engine
+			isolate_namespace Rails::Swagger
+		end
+
+		# Helper method to create a new engine based on a module namespace
+		# prefix and Swagger spec file. The engine ceated will be a subclass of
+		# Rails::Swagger::Engine, which itself inherits from Rails::Engine.
+		def self.Engine base_module, file
+
+			# Convert the module prefix into a constant if passed in as a string
+			base_module = Object.const_get base_module if String === base_module
+
+			# Ensure the Swagger spec file is in an acceptable format
+			ext = File.extname(file)
+			unless ALLOWED_FORMATS.include? ext
+				raise "Swagger files must end with #{ALLOWED_FORMATS.join(' or ')}. File given: #{file}"
+			end
+
+			# Attempt to read and parse the Swagger spec file
+			document = File.read file
+			case File.extname file
+			when ".json"
+				begin
+					require 'json'
+					document = JSON.parse document
+				rescue JSON::ParserError
+					raise $!, "Problem parsing swagger spec file \"#{file}\": #{$!.message.lines.first.strip}", $@
+				end
+			else
+				raise "Swagger files must end with #{ALLOWED_FORMATS.join(' or ')}. File given: #{file}"
+			end
+
+			# Verify that the swagger version is supported
+			unless document["swagger"] == "2.0"
+				raise "Unsupported swagger version: #{document["swagger"]}. #{self} supports only version 2.0"
+			end
+
+			# # Parse the swagger schema
+			# schema = nil
+			# begin
+			# 	schema = JSchema.build document
+			# rescue JSchema::UnknownError, JSchema::InvalidSchema => e
+			# 	raise $!, "Problem parsing swagger spec file \"#{file}\": #{e.message}", $@
+			# end
+
+			# Builds a routing tree based on the swagger spec file.
+			# We'll add each endpoint to the routing tree and additionally
+			# store it in an array to be used below.
+			router = Router.new
+			endpoints = []
+			document["paths"].each do |url, actions|
+				actions.each do |verb, definition|
+					route = Endpoint.new(verb.downcase.to_sym, url, definition)
+					router << route
+					endpoints << route
+				end
+			end
+
+			# Creates the engine that will be used to actually route the
+			# contents of the swagger spec file. The engine will eventually be
+			# attached to the base module (argument to this current method).
+			#
+			# Exposes `::router` and `::endpoints` methods to allow other parts
+			# of the code to tie requests back to their spec file definitions.
+			engine = Class.new Engine do
+
+				@router = router
+				@endpoints = Hash.new
+				@schema = document
+
+				class << self
+					def router
+						@router
+					end
+					def endpoints
+						@endpoints
+					end
+					def schema
+						@schema
+					end
+				end
+
+				# Adds routes to the engine by passing the Mapper to the top
+				# of the routing tree. `self` inside the block refers to an
+				# instance of `ActionDispatch::Routing::Mapper`.
+				self.routes.draw do
+					scope module: base_module.name.underscore, format: false do
+						router.draw self
+					end
+				end
+
+			end
+
+			# Assign the engine as a class on the base module
+			base_module.const_set :Engine, engine
+
+			# Creates a hash that maps routes back to their swagger spec file
+			# equivalents. This is accomplished by mocking a request for each
+			# swagger spec file endpoint and determining which controller and
+			# action the request is routed to. Swagger spec file definitions
+			# are then attached to that controller/action pair.
+			endpoints.each do |route|
+
+				# Mocks a request using the route's URL
+				url = ::ActionDispatch::Journey::Router::Utils.normalize_path route.path
+				env = ::Rack::MockRequest.env_for url, method: route[:method].upcase
+				req = ::ActionDispatch::Request.new env
+
+				# Maps the swagger spec endpoint to the destination controller
+				# action by routing the request.
+				mapped = engine.routes.router.recognize(req){}.first[1]
+				key = "#{mapped[:controller]}##{mapped[:action]}"
+				engine.endpoints[key] = route
+
+			end
+			engine.endpoints.freeze
+
+			# Defines a helper module on the base module that can be used to
+			# properly generate swagger-aware controllers. Any controllers
+			# referenced from a swagger spec file should include this module.
+			mod = Module.new do
+				@base = base_module
+				def self.included controller
+					base_module = @base
+					controller.include Controller
+					define_method :rails_swagger_engine do
+						base_module.const_get :Engine
+					end
+				end
+			end
+			base_module.const_set :SwaggerController, mod
+
+			# Returns the new engine
+			base_module.const_get :Engine
+
+		end
+
+	end
+end

data/lib/rails/swagger/router.rb

@@ -0,0 +1,178 @@
+module Rails
+	module Swagger
+
+		Endpoint = Struct.new(:method, :url, :definition, :_path) do
+			def initialize *opts
+				super
+				self[:_path] = self.path
+			end
+			def path
+				self[:url].gsub /\{(.+)\}/, ':\\1'
+			end
+		end
+
+		RESOURCE_ROUTES = {
+			get: :index,
+			post: :create
+		}.freeze
+		PARAM_ROUTES = {
+			get: :show,
+			patch: :update,
+			put: :update,
+			delete: :destroy
+		}.freeze
+
+		class Router
+
+			attr_accessor :endpoints
+
+			def initialize prefix = [], parent = nil
+				@parent = parent
+				@prefix = prefix
+				@endpoints = []
+				@subroutes = Hash.new do |hash, k|
+					hash[k] = Router.new(@prefix + [k], self)
+				end
+			end
+
+			# Adds an individual endpoint to the routing tree
+			def << route
+				raise "Argument must be an Endpoint" unless Endpoint === route
+				base, *subroute = route[:_path].split '/' # Split out first element
+				if subroute.count == 0
+					route[:_path] = ""
+					@endpoints << route
+				else
+					route[:_path] = subroute.join '/'
+					self[subroute[0]] << route
+				end
+			end
+
+			# Returns a specific branch of the routing tree
+			def [] path
+				@subroutes[path]
+			end
+
+			# Returns the routing path
+			def path
+				"/" + @prefix.join("/")
+			end
+
+			# Returns the mode used for collecting routes
+			def route_mode
+				mode = :resource
+				mode = :namespace if @endpoints.count == 0
+				mode = :action if @subroutes.count == 0 && @parent && @parent.route_mode == :resource
+				mode
+			end
+
+			# Returns the mode used for actions in this router
+			def action_mode
+				if /^:/ === @prefix[-2]
+					:member
+				elsif /^:/ === @prefix[-1]
+					:param
+				else
+					:collection
+				end
+			end
+
+			# Determines the action for a specific route
+			def action_for route
+				raise "Argument must be an Endpoint" unless Endpoint === route
+				action = @prefix[-1]
+				action = PARAM_ROUTES[route[:method]] if self.action_mode == :param
+				action = RESOURCE_ROUTES[route[:method]] if self.route_mode == :resource && self.action_mode == :collection
+				action
+			end
+
+			# Draws the routes for this router
+			def draw map
+				case self.route_mode
+				when :resource
+
+					# Find collection-level resource actions
+					actions = @endpoints.map{ |route| self.action_for route }.select{ |action| Symbol === action }
+
+					# Find parameter-level resource actions
+					@subroutes.select{ |k, subroute| /^:/ === k}.values.each do |subroute|
+						actions += subroute.endpoints.map{ |route| subroute.action_for route }.select{ |action| Symbol === action }
+					end
+
+					map.resources @prefix.last.to_sym, only: actions do
+						draw_actions! map
+						draw_subroutes! map
+					end
+
+				when :namespace
+					if @prefix.join("/").blank?
+						draw_subroutes! map
+					else
+						map.namespace @prefix.last do
+							draw_subroutes! map
+						end
+					end
+				when :action
+					draw_actions! map
+				end
+
+			end
+
+			def routing_tree
+
+				puts self.path + " - #{self.route_mode}"
+				@endpoints.each do |route|
+					puts "\t#{route[:method].to_s.upcase} to ##{self.action_for route} (#{self.action_mode})"
+				end
+				@subroutes.each do |k, subroute| subroute.routing_tree end
+
+			end
+
+			# Outputs the routing tree in text format
+			def to_s
+
+				output = ""
+
+				path = "/" + @prefix.join('/')
+				@endpoints.each do |route|
+					output += "#{route[:method].to_s.upcase} #{path}\n"
+				end
+				@subroutes.each do |k, subroute|
+					output += subroute.to_s
+				end
+
+				output
+
+			end
+
+		protected
+
+			def draw_actions! map
+				indent = "\t" * @prefix.count
+				endpoint = @prefix.last
+				@endpoints.each do |route|
+
+					params = Hash.new
+					params[:via] = route[:method]
+					params[:on] = self.action_mode unless self.action_mode == :param
+					params[:action] = self.action_for route
+
+					# These are handled in the resource
+					next if Symbol === params[:action]
+
+					# Add this individual route
+					map.match endpoint, params
+
+				end
+			end
+
+			def draw_subroutes! map
+				@subroutes.values.each do |subroute|
+					subroute.draw map
+				end
+			end
+
+		end
+
+	end
+end

data/lib/rails/swagger.rb

@@ -0,0 +1,9 @@
+require "jschema"
+require "rails/swagger/controller"
+require "rails/swagger/router"
+require "rails/swagger/engine"
+
+module Rails
+	module Swagger
+	end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: rails-swagger
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Kenaniah Cerny
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-04-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jschema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  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'
+- !ruby/object:Gem::Dependency
+  name: rails
+  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'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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: 
+email:
+- kenaniah@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/rails/swagger.rb
+- lib/rails/swagger/controller.rb
+- lib/rails/swagger/engine.rb
+- lib/rails/swagger/router.rb
+homepage: https://github.com/kenaniah/rails-swagger
+licenses: []
+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.6.8
+signing_key: 
+specification_version: 4
+summary: Turns Swagger API schemas into mountable Rails engines
+test_files: []