rails-openapi 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6012b8d66ea54b85a1856f9072bdefd89714d92a2b101798d86f9c19a4a15961
+  data.tar.gz: 0c2206e467404c49f60c7e022058fc7cf8751537339a80f4458d32ad29bbe75d
+SHA512:
+  metadata.gz: 0ef32988bf178e4f9e37e798bc86e4ff1ccc129b41e104017f93ffcd185ee3c8ec7684430e3ffedc3c79eac07f85614662ec815cc7f118dcd9a522dd2c1e30cd
+  data.tar.gz: '087a18d21c99dba35f372f344b3226c536d656b8c4d33971761018b8e0db187574adad1c9904357ff8f68c619ae1cbf7ef4d2bdafd6e96d88ec37ed6d4546fe7'

data/lib/rails/openapi/engine.rb

@@ -0,0 +1,143 @@
+module Rails
+  module Openapi
+    # Defines a base class from which OpenAPI 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::Openapi
+    end
+
+    # Helper method to create a new engine based on a module namespace prefix and an OpenAPI spec file
+    def self.Engine namespace:, schema:, publish_schema: true
+      # Convert the module prefix into a constant if passed in as a string
+      base_module = Object.const_get namespace if String === namespace
+
+      # Ensure the OpenAPI spec file is in an acceptable format
+      begin
+        require "yaml"
+        document = YAML.safe_load schema
+        unless document.is_a?(Hash) && document["openapi"].present?
+          raise "The schema argument could not be parsed as an OpenAPI schema"
+        end
+        unless Gem::Version.new(document["openapi"]) >= Gem::Version.new("3.0")
+          raise "The schema argument must be an OpenAPI 3.0+ schema. You passed in a schema with version #{document["openapi"]}"
+        end
+      rescue Psych::SyntaxError
+        raise $!, "Problem parsing OpenAPI schema: #{$!.message.lines.first.strip}", $@
+      end
+
+      # Builds a routing tree based on the OpenAPI 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|
+          next if verb == "parameters"
+          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 OpenAPI 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 = {}
+        @schema = document.freeze
+
+        class << self
+          attr_reader :router
+
+          attr_reader :endpoints
+
+          attr_reader :schema
+        end
+
+        # Rack app for serving the original OpenAPI file
+        openapi_app = Class.new do
+          def inspect
+            "Rails::Openapi::Engine"
+          end
+          define_method :call do |env|
+            [
+              200,
+              {"Content-Type" => "application/json"},
+              [engine.schema.to_json]
+            ]
+          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`.
+        routes.draw do
+          scope module: base_module.name.underscore, format: false do
+            get "openapi.json", to: openapi_app.new, as: :openapi_schema if publish_schema
+            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 OpenAPI spec file
+      # equivalents. This is accomplished by mocking a request for each
+      # OpenAPI spec file endpoint and determining which controller and
+      # action the request is routed to. OpenAPI 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 OpenAPI spec endpoint to the destination controller
+        # action by routing the request.
+        begin
+          mapped = engine.routes.router.recognize(req) {}.first[2].defaults
+        rescue
+          Rails.logger.error "Could not resolve the OpenAPI route for #{req.method} #{req.url}"
+          next
+        end
+        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 OpenAPI-aware controllers. Any controllers
+      # referenced from a OpenAPI spec file should include this module.
+      mod = Module.new do
+        @base = base_module
+        def self.included controller
+          base_module = @base
+          # Returns a reference to the Rails engine generated for this OpenAPI spec file
+          define_method :openapi_engine do
+            base_module.const_get :Engine
+          end
+          # Returns the OpenAPI schema used to generate the Rails engine as a Hash
+          define_method :openapi_schema do
+            base_module.const_get(:Engine).schema
+          end
+          # Returns the OpenAPI spec's endpoint definition for current request
+          define_method :openapi_endpoint do
+            openapi_engine.endpoints["#{request.path_parameters[:controller]}##{request.path_parameters[:action]}"]
+          end
+          # Allows the helper methods to also be used in views
+          controller.helper_method :openapi_engine, :openapi_schema, :openapi_endpoint
+        end
+      end
+      base_module.const_set :OpenapiHelper, mod
+
+      # Returns the new engine
+      base_module.const_get :Engine
+    end
+  end
+end

data/lib/rails/openapi/router.rb

@@ -0,0 +1,214 @@
+module Rails
+  module Openapi
+    # Internally represents individual routes
+    Endpoint = Struct.new(:method, :url, :definition, :_path) do
+      def initialize *opts
+        super
+        self[:_path] = path
+      end
+
+      # Translates path params from {bracket} syntax to :symbol syntax
+      def path
+        self[:url].gsub(/\{([^}]+)\}/, ':\\1')
+      end
+    end
+
+    # Defines RESTful routing conventions
+    RESOURCE_ROUTES = {
+      get: :index,
+      post: :create,
+      put: :update,
+      patch: :update,
+      delete: :destroy
+    }.freeze
+    PARAM_ROUTES = {
+      get: :show,
+      post: :update,
+      patch: :update,
+      put: :update,
+      delete: :destroy
+    }.freeze
+
+    class Router
+      attr_accessor :endpoints
+
+      def initialize prefix = [], parent = nil
+        @parent = parent
+        @prefix = prefix.freeze
+        @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 = :param if /^:/.match?(@prefix.last)
+        mode
+      end
+
+      # Returns the mode used for actions in this router
+      def action_mode
+        if /^:/.match?(@prefix[-1])
+          :member
+        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]&.underscore || ""
+        action = PARAM_ROUTES[route[:method]] if action_mode == :member
+        action = RESOURCE_ROUTES[route[:method]] if route_mode == :resource && action_mode == :collection
+        action
+      end
+
+      # Draws the routes for this router
+      def draw map
+        case route_mode
+        when :resource
+
+          # Find collection-level resource actions
+          actions = @endpoints.map { |r| action_for r }.select { |a| Symbol === a }
+
+          # Find parameter-level resource actions
+          @subroutes.select { |k, _| /^:/ === k }.values.each do |subroute|
+            actions += subroute.endpoints.map { |r| subroute.action_for r }.select { |a| Symbol === a }
+          end
+
+          # Determine if this is a collection or a singleton resource
+          type = @subroutes.any? { |k, _| /^:/ === k } ? :resources : :resource
+          if type == :resource && actions.include?(:index)
+            # Remap index to show for singleton resources
+            actions.delete :index
+            actions << :show
+          end
+
+          # Draw the resource
+          map.send type, @prefix.last&.to_sym || "/", controller: @prefix.last&.underscore || "main", only: actions, as: @prefix.last&.underscore || "main", format: nil do
+            # Draw custom actions
+            draw_actions! map
+
+            # Handle the edge case in which POST is used instead of PUT/PATCH
+            draw_post_updates! map
+
+            # Draw a namespace (unless at the top)
+            if @prefix.join("/").blank?
+              draw_subroutes! map
+            else
+              map.scope module: @prefix.last do
+                draw_subroutes! map
+              end
+            end
+          end
+
+        when :namespace
+
+          # Draw a namespace (unless at the top)
+          if @prefix.join("/").blank?
+            draw_subroutes! map
+          else
+            map.namespace @prefix.last do
+              draw_subroutes! map
+            end
+          end
+
+        when :param
+
+          # Draw subroutes directly
+          draw_subroutes! map
+          draw_actions! map
+
+        when :action
+          # Draw actions directly
+          draw_actions! map
+
+        end
+      end
+
+      # Returns 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
+
+      # Outputs a visual representation of the routing tree
+      def _debug_routing_tree
+        puts path + " - #{route_mode}"
+        @endpoints.each do |route|
+          puts "\t#{route[:method].to_s.upcase} to ##{action_for route} (#{action_mode})"
+        end
+        @subroutes.each { |k, subroute| subroute._debug_routing_tree }
+      end
+
+      protected
+
+      # Some APIs use the POST verb instead of PUT/PATCH for updating resources
+      def draw_post_updates! map
+        @subroutes.select { |k, _| /^:/ === k }.each do |param, subroute|
+          if subroute.endpoints.select { |r| r[:method] == :post }.any?
+            map.match param, via: :post, action: :update, on: :collection
+          end
+        end
+      end
+
+      def draw_actions! map
+        @endpoints.each do |route|
+          # Params hash for the route to be added
+          params = {}
+          params[:via] = route[:method]
+          params[:action] = action_for route
+          params[:on] = action_mode unless action_mode == :member
+          params[:as] = @prefix.last&.underscore
+
+          # Skip actions that are handled in the resource level
+          next if Symbol === params[:action]
+
+          # Add this individual route
+          map.match @prefix.last, params
+        end
+      end
+
+      def draw_subroutes! map
+        @subroutes.values.each { |r| r.draw map }
+      end
+    end
+  end
+end

data/lib/rails/openapi/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Rails
+  module Openapi
+    VERSION = "1.0.0"
+  end
+end

data/lib/rails/openapi.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "rails"
+require_relative "openapi/version"
+require_relative "openapi/engine"
+require_relative "openapi/router"

data/sig/rails/openapi.rbs

@@ -0,0 +1,6 @@
+module Rails
+  module Openapi
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: rails-openapi
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Kenaniah Cerny
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-07-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+- !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: colorize
+  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: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description:
+email:
+- kenaniah@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/rails/openapi.rb
+- lib/rails/openapi/engine.rb
+- lib/rails/openapi/router.rb
+- lib/rails/openapi/version.rb
+- sig/rails/openapi.rbs
+homepage: https://github.com/kenaniah/rails-openapi
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kenaniah/rails-openapi
+  source_code_uri: https://github.com/kenaniah/rails-openapi
+  changelog_uri: https://github.com/kenaniah/rails-openapi/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.33
+signing_key:
+specification_version: 4
+summary: Creates rails engines from OpenAPI specification files
+test_files: []