rspec-rails-swagger 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ee3d27df0e7ec24ced93bd4a298f649b86715b12
+  data.tar.gz: 0e96a4167c43c555b94b81d93901939311e0dd98
+SHA512:
+  metadata.gz: 217c592d0a3331819d7264a7356885ec3e69d8cc075aa7a6f98e524f5dcf96466adefefd16214772abdbd42a494f5df78d4bc3e6cc1482f86c797d3f12bc0c35
+  data.tar.gz: d9b5651ac3f9c4a76c09ca9efce6e0f671f4c5264c79dfaa0356ada5e7f13c18cdf1336352a7e8f0a9a70fb45cd427f1fd591015d755c63442c85d359f86eb66

data/lib/rspec/rails/swagger.rb

@@ -0,0 +1,16 @@
+require 'rspec/core'
+require 'rspec/rails/swagger/configuration'
+require 'rspec/rails/swagger/document'
+require 'rspec/rails/swagger/formatter'
+require 'rspec/rails/swagger/helpers'
+require 'rspec/rails/swagger/request_builder'
+require 'rspec/rails/swagger/version'
+
+module RSpec
+  module Rails
+    module Swagger
+      initialize_configuration RSpec.configuration
+    end
+  end
+end
+

data/lib/rspec/rails/swagger/configuration.rb

@@ -0,0 +1,16 @@
+module RSpec
+  module Rails
+    module Swagger
+      # Fake class to document RSpec Swagger configuration options.
+      class Configuration
+      end
+
+      def self.initialize_configuration(config)
+        config.add_setting :swagger_root
+        config.add_setting :swagger_docs, default: {}
+
+        Helpers.add_swagger_type_configurations(config)
+      end
+    end
+  end
+end

data/lib/rspec/rails/swagger/document.rb

@@ -0,0 +1,32 @@
+module RSpec
+  module Rails
+    module Swagger
+      class Document
+        attr_accessor :data
+
+        def initialize(data)
+          @data = data.deep_symbolize_keys
+        end
+
+        def [](value)
+          data[value]
+        end
+
+        def resolve_ref(ref)
+          unless %r{#/(?<location>parameters|definitions)/(?<name>.+)} =~ ref
+            raise ArgumentError, "Invalid reference: #{ref}"
+          end
+
+          result = data.fetch(location.to_sym, {})[name.to_sym]
+          raise ArgumentError, "Reference value does not exist: #{ref}" unless result
+
+          if location == 'parameters'
+            result.merge(name: name)
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/rspec/rails/swagger/formatter.rb

@@ -0,0 +1,105 @@
+require 'rspec/core/formatters/base_text_formatter'
+
+module RSpec
+  module Rails
+    module Swagger
+      class Formatter < RSpec::Core::Formatters::BaseTextFormatter
+        RSpec::Core::Formatters.register self, :example_finished, :close
+
+        def documents
+          # We don't try to load the docs in `initalize` because when running
+          # `rspec -f RSpec::Swagger::Formatter` RSpec initalized this class
+          # before `swagger_helper` has run.
+          @documents ||= ::RSpec.configuration.swagger_docs
+        end
+
+        def example_finished(notification)
+          metadata  = notification.example.metadata
+          return unless metadata[:swagger_object] == :response
+
+          # metadata.each do |k, v|
+          #   puts "#{k}\t#{v}" if k.to_s.starts_with?("swagger")
+          # end
+
+          document  = document_for(metadata[:swagger_document])
+          path_item = path_item_for(document, metadata[:swagger_path_item])
+          operation = operation_for(path_item, metadata[:swagger_operation])
+                      response_for(operation, metadata[:swagger_response])
+        end
+
+        def close(_notification)
+          documents.each{|k, v| write_json(k, v)}
+        end
+
+        def write_json(name, document)
+          root = ::RSpec.configuration.swagger_root
+          # It would be good to at least warn if the name includes some '../' that
+          # takes it out of root directory.
+          target = Pathname(name).expand_path(root)
+          target.dirname.mkpath
+          target.write(JSON.pretty_generate(document))
+        end
+
+        def document_for(doc_name = nil)
+          if doc_name
+            documents.fetch(doc_name)
+          else
+            documents.values.first
+          end
+        end
+
+        def path_item_for(document, swagger_path_item)
+          name = swagger_path_item[:path]
+
+          document[:paths] ||= {}
+          document[:paths][name] ||= {}
+          if swagger_path_item[:parameters]
+            document[:paths][name][:parameters] = prepare_parameters(swagger_path_item[:parameters])
+          end
+          document[:paths][name]
+        end
+
+        def operation_for(path, swagger_operation)
+          method = swagger_operation[:method]
+
+          path[method] ||= {responses: {}}
+          path[method].tap do |operation|
+            if swagger_operation[:parameters]
+              operation[:parameters] = prepare_parameters(swagger_operation[:parameters])
+            end
+            operation.merge!(swagger_operation.slice(
+              :summary, :description, :externalDocs, :operationId,
+              :consumes, :produces, :schemes, :deprecated, :security
+            ))
+          end
+        end
+
+        def response_for(operation, swagger_response)
+          status = swagger_response[:status_code]
+
+          operation[:responses][status] ||= {}
+          operation[:responses][status].tap do |response|
+            if swagger_response[:examples]
+              response[:examples] = prepare_examples(swagger_response[:examples])
+            end
+            response.merge!(swagger_response.slice(:description, :schema, :headers))
+          end
+        end
+
+        def prepare_parameters(params)
+          params.values
+        end
+
+        def prepare_examples(examples)
+          if examples["application/json"].present?
+            begin
+              examples["application/json"] = JSON.parse(examples["application/json"])
+            rescue JSON::ParserError
+            end
+          end
+          examples
+        end
+      end
+    end
+  end
+end

data/lib/rspec/rails/swagger/helpers.rb

@@ -0,0 +1,258 @@
+module RSpec
+  module Rails
+    module Swagger
+      module Helpers
+        # paths: (Paths)
+        #   /pets: (Path Item)
+        #     post: (Operation)
+        #       tags:
+        #         - pet
+        #       summary: Add a new pet to the store
+        #       description: ""
+        #       operationId: addPet
+        #       consumes:
+        #         - application/json
+        #       produces:
+        #         - application/json
+        #       parameters: (Parameters)
+        #         - in: body
+        #           name: body
+        #           description: Pet object that needs to be added to the store
+        #           required: false
+        #           schema:
+        #             $ref: "#/definitions/Pet"
+        #       responses: (Responses)
+        #         "405": (Response)
+        #           description: Invalid input
+
+        # The helpers serve as a DSL.
+        def self.add_swagger_type_configurations(config)
+          # The filters are used to ensure that the methods are nested correctly
+          # and following the Swagger schema.
+          config.extend Paths,       type: :request
+          config.extend PathItem,    swagger_object: :path_item
+          config.extend Parameters,  swagger_object: :path_item
+          config.extend Operation,   swagger_object: :operation
+          config.extend Parameters,  swagger_object: :operation
+          config.extend Response,    swagger_object: :response
+        end
+
+        module Paths
+          def path template, attributes = {}, &block
+            attributes.symbolize_keys!
+
+            raise ArgumentError, "Path must start with a /" unless template.starts_with?('/')
+
+            #TODO template might be a $ref
+            meta = {
+              swagger_object: :path_item,
+              swagger_document: attributes[:swagger_document] || RSpec.configuration.swagger_docs.keys.first,
+              swagger_path_item: {path: template}
+            }
+            describe(template, meta, &block)
+          end
+        end
+
+        module PathItem
+          METHODS = %w(get put post delete options head patch).freeze
+
+          def operation method, attributes = {}, &block
+            attributes.symbolize_keys!
+
+            method = method.to_s.downcase
+            validate_method! method
+
+            meta = {
+              swagger_object: :operation,
+              swagger_operation: attributes.merge(method: method.to_sym).reject{ |v| v.nil? }
+            }
+            describe(method.to_s, meta, &block)
+          end
+
+          METHODS.each do |method|
+            define_method(method) do |attributes = {}, &block|
+              operation(method, attributes, &block)
+            end
+          end
+
+          private
+
+          def validate_method! method
+            unless METHODS.include? method.to_s
+              raise ArgumentError, "Operation has an invalid 'method' value. Try: #{METHODS}."
+            end
+          end
+        end
+
+        module Parameters
+          def parameter name, attributes = {}
+            attributes.symbolize_keys!
+
+            # Look for $refs
+            if name.respond_to?(:has_key?)
+              ref = name.delete(:ref) || name.delete('ref')
+              full_param = resolve_document(metadata).resolve_ref(ref)
+
+              validate_parameter! full_param
+
+              param = { '$ref' => ref }
+              key = parameter_key(full_param)
+            else
+              validate_parameter! attributes
+
+              # Path attributes are always required
+              attributes[:required] = true if attributes[:in] == :path
+
+              param = { name: name.to_s }.merge(attributes)
+              key = parameter_key(param)
+            end
+
+            parameters_for_object[key] = param
+          end
+
+          def resolve_document metadata
+            # TODO: It's really inefficient to keep recreating this. It'd be nice
+            # if we could cache them some place.
+            name = metadata[:swagger_document]
+            Document.new(RSpec.configuration.swagger_docs[name])
+          end
+
+          private
+
+          # This key ensures uniqueness based on the 'name' and 'in' values.
+          def parameter_key parameter
+            "#{parameter[:in]}&#{parameter[:name]}"
+          end
+
+          def parameters_for_object
+            object_key = "swagger_#{metadata[:swagger_object]}".to_sym
+            object_data = metadata[object_key] ||= {}
+            object_data[:parameters] ||= {}
+          end
+
+          def validate_parameter! attributes
+            validate_location! attributes[:in]
+
+            if attributes[:in].to_s == 'body'
+              unless attributes[:schema].present?
+                raise ArgumentError, "Parameter is missing required 'schema' value."
+              end
+            else
+              validate_type! attributes[:type]
+            end
+          end
+
+          def validate_location! location
+            unless location.present?
+              raise ArgumentError, "Parameter is missing required 'in' value."
+            end
+
+            locations = %w(query header path formData body)
+            unless locations.include? location.to_s
+              raise ArgumentError, "Parameter has an invalid 'in' value. Try: #{locations}."
+            end
+          end
+
+          def validate_type! type
+            unless type.present?
+              raise ArgumentError, "Parameter is missing required 'type' value."
+            end
+
+            types = %w(string number integer boolean array file)
+            unless types.include? type.to_s
+              raise ArgumentError, "Parameter has an invalid 'type' value. Try: #{types}."
+            end
+          end
+        end
+
+        module Operation
+          def consumes *mime_types
+            metadata[:swagger_operation][:consumes] = mime_types
+          end
+
+          def produces *mime_types
+            metadata[:swagger_operation][:produces] = mime_types
+          end
+
+          def response status_code, attributes = {}, &block
+            attributes.symbolize_keys!
+
+            validate_status_code! status_code
+            validate_description! attributes[:description]
+
+            meta = {
+              swagger_object: :response,
+              swagger_response: attributes.merge(status_code: status_code)
+            }
+            describe(status_code, meta) do
+              self.module_exec(&block) if block_given?
+
+              # To make a request we need:
+              # - the details we've collected in the metadata
+              # - parameter values defined using let()
+              # RSpec tries to limit access to metadata inside of it() / before()
+              # / after() blocks but that scope is the only place you can access
+              # the let() values. The solution the swagger_rails dev came up with
+              # is to use the example.metadata passed into the block with the
+              # block's scope which has access to the let() values.
+              before do |example|
+                builder = RequestBuilder.new(example.metadata, self)
+                method = builder.method
+                path = [builder.path, builder.query].join
+                headers = builder.headers
+                body = builder.body
+
+                # Run the request
+                if ::Rails::VERSION::MAJOR >= 5
+                  self.send(method, path, {params: body, headers: headers})
+                else
+                  self.send(method, path, body, headers)
+                end
+
+                if example.metadata[:capture_examples]
+                  examples = example.metadata[:swagger_response][:examples] ||= {}
+                  examples[response.content_type.to_s] = response.body
+                end
+              end
+
+              # TODO: see if we can get the caller to show up in the error
+              # backtrace for this test.
+              it("returns the correct status code") do
+                expect(response).to have_http_status(status_code)
+              end
+            end
+          end
+
+          private
+
+          def validate_status_code! status_code
+            unless status_code == :default || (100..599).cover?(status_code)
+              raise ArgumentError, "status_code must be an integer 100 to 599, or :default"
+            end
+          end
+
+          def validate_description! description
+            unless description.present?
+              raise ArgumentError, "Response is missing required 'description' value."
+            end
+          end
+        end
+
+        module Response
+          def capture_example
+            metadata[:capture_examples] = true
+          end
+
+          def schema definition
+            definition.symbolize_keys!
+
+            ref = definition.delete(:ref)
+            schema = ref ? { '$ref' => ref } : definition
+
+            metadata[:swagger_response][:schema] = schema
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/rails/swagger/request_builder.rb

@@ -0,0 +1,91 @@
+module RSpec
+  module Rails
+    module Swagger
+      class RequestBuilder
+        attr_reader :metadata, :instance
+
+        def initialize(metadata, instance)
+          @metadata, @instance = metadata, instance
+        end
+
+        def document
+          @document ||= begin
+            name = metadata[:swagger_document]
+            Document.new(RSpec.configuration.swagger_docs[name])
+          end
+        end
+
+        def method
+          metadata[:swagger_operation][:method]
+        end
+
+        def produces
+          metadata[:swagger_operation][:produces] || document[:produces]
+        end
+
+        def consumes
+          metadata[:swagger_operation][:consumes] || document[:consumes]
+        end
+
+        def parameters location = nil
+          path_item = metadata[:swagger_path_item] || {}
+          operation = metadata[:swagger_operation] || {}
+          params = path_item.fetch(:parameters, {}).merge(operation.fetch(:parameters, {}))
+          if location.present?
+            params.select{ |k, _| k.starts_with? "#{location}&" }
+          else
+            params
+          end
+        end
+
+        def parameter_values location
+          # Don't bother looking at the full parameter bodies since all we need
+          # are location and name which are in the key.
+          values = parameters(location)
+            .keys
+            .map{ |k| k.split('&').last }
+            .map{ |name| [name, instance.send(name)] }
+          Hash[values]
+        end
+
+        def headers
+          headers = {}
+
+          # Match the names that Rails uses internally
+          headers['HTTP_ACCEPT'] = produces.join(';') if produces.present?
+          headers['CONTENT_TYPE'] = consumes.first if consumes.present?
+
+          # TODO: do we need to do some capitalization to match the rack
+          # conventions?
+          parameter_values(:header).each { |k, v| headers[k] = v }
+
+          headers
+        end
+
+        def path
+          base_path = document[:basePath] || ''
+          # Find params in the path and replace them with values defined in
+          # in the example group.
+          base_path + metadata[:swagger_path_item][:path].gsub(/(\{.*?\})/) do |match|
+            # QUESTION: Should check that the parameter is actually defined in
+            # `parameters` before fetch a value?
+            instance.send(match[1...-1])
+          end
+        end
+
+        def query
+          query_params = parameter_values(:query).to_query
+          "?#{query_params}" unless query_params.blank?
+        end
+
+        def body
+          # And here all we need is the first half of the key to find the body
+          # parameter and its name to fetch a value.
+          if key = parameters(:body).keys.first
+            instance.send(key.split('&').last).to_json
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/rails/swagger/version.rb

@@ -0,0 +1,10 @@
+module RSpec
+  module Rails
+    # Version information for RSpec Swagger.
+    module Swagger
+      module Version
+        STRING = '0.1.0'
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: rspec-rails-swagger
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- andrew morton
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-09-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Inspired by swagger_rails
+email: drewish@katherinehouse.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/rspec/rails/swagger.rb
+- lib/rspec/rails/swagger/configuration.rb
+- lib/rspec/rails/swagger/document.rb
+- lib/rspec/rails/swagger/formatter.rb
+- lib/rspec/rails/swagger/helpers.rb
+- lib/rspec/rails/swagger/request_builder.rb
+- lib/rspec/rails/swagger/version.rb
+homepage: https://github.com/drewish/rspec-rails-swagger
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Generate Swagger docs from RSpec integration tests
+test_files: []