rspec-swag 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 725c8f570fabf5d664224343b2241b840ca69ad177973cdb0fb1c4938318c134
+  data.tar.gz: 598a18e4bfe3321f8361668f9340b36607a6cd4a54678489b7e98bd974e6d343
+SHA512:
+  metadata.gz: 64d7acf87b824fdb1419f0c12f3dd7015b789a4613b1c7459fedd9191a69bc825a5a30c86aa6b01582705e5583b3a3301bf4404ff28ba56151b3beedf2527b99
+  data.tar.gz: a3cded64dbf1e3e2fd87a8c908341210bca6f00d19b8741475aaad2a14a3362149563d7a77984b99ed0fe50919414111c9b8652a3e660db3bad318c04a274280

data/.rubocop_rspec_alias_config.yml

@@ -0,0 +1,17 @@
+RSpec:
+  Language:
+    ExampleGroups:
+      Regular:
+        - path
+        - response
+        - get
+        - post
+        - patch
+        - put
+        - delete
+        - head
+        - options
+        - trace
+    Examples:
+      Regular:
+        - run_test!

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2024 GracefulPotato
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,25 @@
+#!/usr/bin/env rake
+
+# frozen_string_literal: true
+
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
+begin
+  require "rdoc/task"
+rescue LoadError
+  require "rdoc/rdoc"
+  require "rake/rdoctask"
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title    = "rspec-swag"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+Bundler::GemHelper.install_tasks

data/lib/rspec/swag/configuration.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Swag
+    class Configuration
+      def initialize(rspec_config)
+        @rspec_config = rspec_config
+      end
+
+      def openapi_root
+        @openapi_root ||=
+          @rspec_config.openapi_root || raise(ConfigurationError, "No openapi_root provided. See swagger_helper.rb")
+      end
+
+      def openapi_specs
+        @openapi_specs ||= begin
+          if @rspec_config.openapi_specs.nil? || @rspec_config.openapi_specs.empty?
+            raise ConfigurationError, "No openapi_specs defined. See swagger_helper.rb"
+          end
+
+          @rspec_config.openapi_specs
+        end
+      end
+
+      def swagger_dry_run
+        @swagger_dry_run ||= begin
+          @rspec_config.swagger_dry_run = ENV["SWAGGER_DRY_RUN"] == "1" if ENV.key?("SWAGGER_DRY_RUN")
+
+          @rspec_config.swagger_dry_run.nil? || @rspec_config.swagger_dry_run
+        end
+      end
+
+      def openapi_format
+        @openapi_format ||= begin
+          if @rspec_config.openapi_format.nil? || @rspec_config.openapi_format.empty?
+            @rspec_config.openapi_format = :json
+          end
+
+          unless [:json, :yaml].include?(@rspec_config.openapi_format)
+            raise ConfigurationError, "Unknown openapi_format '#{@rspec_config.openapi_format}'"
+          end
+
+          @rspec_config.openapi_format
+        end
+      end
+
+      def get_openapi_spec(name)
+        return openapi_specs.values.first if name.nil?
+        raise ConfigurationError, "Unknown openapi_spec '#{name}'" unless openapi_specs[name]
+
+        openapi_specs[name]
+      end
+
+      def get_openapi_spec_version(name)
+        doc = get_openapi_spec(name)
+        doc[:openapi] || doc[:swagger]
+      end
+
+      def openapi_strict_schema_validation
+        @rspec_config.openapi_strict_schema_validation || false
+      end
+    end
+
+    class ConfigurationError < StandardError; end
+  end
+end

data/lib/rspec/swag/example_group_helpers.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "active_support"
+
+module RSpec
+  module Swag
+    module ExampleGroupHelpers
+      def path(template, metadata = {}, &block)
+        metadata[:path_item] = { template: template }
+        describe(template, metadata, &block)
+      end
+
+      [:get, :post, :patch, :put, :delete, :head, :options, :trace].each do |verb|
+        define_method(verb) do |summary, **metadata, &block|
+          api_metadata = { operation: { verb: verb, summary: summary } }.deep_merge(metadata)
+          describe(verb, **api_metadata, &block)
+        end
+      end
+
+      [:operationId, :deprecated, :security].each do |attr_name|
+        define_method(attr_name) do |value|
+          metadata[:operation][attr_name] = value
+        end
+      end
+
+      # NOTE: 'description' requires special treatment because ExampleGroup already
+      # defines a method with that name. Provide an override that supports the existing
+      # functionality while also setting the appropriate metadata if applicable
+      def description(value = nil)
+        return super() if value.nil?
+
+        metadata[:operation][:description] = value
+      end
+
+      # These are array properties - note the splat operator
+      [:tags, :consumes, :produces, :schemes].each do |attr_name|
+        define_method(attr_name) do |*value|
+          metadata[:operation][attr_name] = value
+        end
+      end
+
+      def parameter(attributes)
+        attributes[:required] = true if attributes[:in] && attributes[:in].to_sym == :path
+
+        if metadata.key?(:operation)
+          metadata[:operation][:parameters] ||= []
+          metadata[:operation][:parameters] << attributes
+        else
+          metadata[:path_item][:parameters] ||= []
+          metadata[:path_item][:parameters] << attributes
+        end
+      end
+
+      def request_body_example(value:, summary: nil, name: nil)
+        return unless metadata.key?(:operation)
+
+        metadata[:operation][:request_examples] ||= []
+        example = { value: value }
+        example[:summary] = summary if summary
+        # We need the examples to have a unique name for a set of examples,
+        # so just make the name the length if one isn't provided.
+        example[:name] = name || metadata[:operation][:request_examples].length
+        metadata[:operation][:request_examples] << example
+      end
+
+      def response(code, description, metadata = {}, &block)
+        metadata[:response] = { code: code, description: description }
+        context(description, metadata, &block)
+      end
+
+      def schema(value)
+        metadata[:response][:schema] = value
+      end
+
+      def header(name, attributes)
+        metadata[:response][:headers] ||= {}
+
+        metadata[:response][:headers][name] = attributes
+      end
+
+      # NOTE: Similar to 'description', 'examples' need to handle the case when
+      # being invoked with no params to avoid overriding 'examples' method of
+      # rspec-core ExampleGroup
+      def examples(examples = nil)
+        return super() if examples.nil?
+
+        # should we add a deprecation warning?
+        examples.each_with_index do |(mime, example_object), index|
+          example(mime, "example_#{index}", example_object)
+        end
+      end
+
+      def example(mime, name, value, summary = nil, description = nil)
+        # Todo - move initialization of metadata somewhere else.
+        metadata[:response][:content] = {} if metadata[:response][:content].blank?
+
+        if metadata[:response][:content][mime].blank?
+          metadata[:response][:content][mime] = {}
+          metadata[:response][:content][mime][:examples] = {}
+        end
+
+        example_object = {
+          value: value,
+          summary: summary,
+          description: description
+        }.select { |_, v| v.present? }
+        # TODO, issue a warning if example is being overridden with the same key
+        metadata[:response][:content][mime][:examples].merge!(
+          { name.to_sym => example_object }
+        )
+      end
+
+      #
+      # Perform request and assert response matches swagger definitions
+      #
+      # @param description [String] description of the test
+      # @param args [Array] arguments to pass to the `it` method
+      # @param options [Hash] options to pass to the `it` method
+      # @param &block [Proc] you can make additional assertions within that block
+      # @return [void]
+      def run_test!(description = nil, *args, **options, &block)
+        # swagger metadata value defaults to true
+        options[:swagger] = true unless options.key?(:swagger)
+
+        description ||= "returns a #{metadata[:response][:code]} response"
+
+        before do |example|
+          submit_request(example.metadata)
+        end
+
+        it description, *args, **options do |example|
+          assert_response_matches_metadata(example.metadata, &block)
+          example.instance_exec(last_response, &block) if block_given?
+        end
+      end
+    end
+  end
+end

data/lib/rspec/swag/example_helpers.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rspec/swag/request_factory"
+require "rspec/swag/response_validator"
+
+module RSpec
+  module Swag
+    module ExampleHelpers
+      def submit_request(metadata)
+        request = RequestFactory.new.build_request(metadata, self)
+
+        send(
+          request[:verb],
+          request[:path],
+          request[:payload],
+          request[:headers]
+        )
+      end
+
+      def assert_response_matches_metadata(metadata)
+        ResponseValidator.new.validate!(metadata, last_response)
+      end
+    end
+  end
+end

data/lib/rspec/swag/extended_schema.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "json-schema"
+
+module RSpec
+  module Swag
+    class ExtendedSchema < JSON::Schema::Draft4
+      def initialize
+        super
+        @uri = URI.parse("http://tempuri.org/rswag/specs/extended_schema")
+        @names = ["http://tempuri.org/rswag/specs/extended_schema"]
+      end
+
+      def validate(current_schema, data, *)
+        if data.nil? && (current_schema.schema["nullable"] == true || current_schema.schema["x-nullable"] == true)
+          return
+        end
+
+        super
+      end
+    end
+
+    JSON::Validator.register_validator(ExtendedSchema.new)
+  end
+end

data/lib/rspec/swag/project_initializer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module RSpec
+  module Swag
+    class ProjectInitializer
+      attr_reader :destination, :source
+
+      def initialize
+        @destination = Dir.pwd
+        @source = File.expand_path("templates", __dir__)
+      end
+
+      def run
+        copy_template "spec/swagger_helper.rb"
+      end
+
+      private
+
+      def copy_template(file)
+        destination_file = File.join(destination, file)
+        return report_exists(file) if File.exist?(destination_file)
+
+        report_creating(file)
+        FileUtils.mkdir_p(File.dirname(destination_file))
+        File.open(destination_file, "w") do |f|
+          f.write File.read(File.join(source, file))
+        end
+      end
+
+      def report_exists(file)
+        puts "   exist   #{file}"
+      end
+
+      def report_creating(file)
+        puts "  create   #{file}"
+      end
+    end
+  end
+end

data/lib/rspec/swag/rake_task.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "rake"
+load "rspec/swag/tasks/rspec_swag_tasks.rake"

data/lib/rspec/swag/request_factory.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/hash/slice"
+require "active_support/core_ext/hash/conversions"
+require "json"
+
+module RSpec
+  module Swag
+    # rubocop:disable Metrics/ClassLength
+    class RequestFactory
+      def initialize(config = ::RSpec::Swag.config)
+        @config = config
+      end
+
+      def build_request(metadata, example)
+        swagger_doc = @config.get_openapi_spec(metadata[:openapi_spec] || metadata[:swagger_doc])
+        parameters = expand_parameters(metadata, swagger_doc, example)
+
+        {}.tap do |request|
+          add_verb(request, metadata)
+          add_path(request, metadata, swagger_doc, parameters, example)
+          add_headers(request, metadata, swagger_doc, parameters, example)
+          add_payload(request, parameters, example)
+        end
+      end
+
+      private
+
+      def expand_parameters(metadata, swagger_doc, example)
+        operation_params = metadata[:operation][:parameters] || []
+        path_item_params = metadata[:path_item][:parameters] || []
+        security_params = derive_security_params(metadata, swagger_doc)
+
+        # NOTE: Use of + instead of concat to avoid mutation of the metadata object
+        (operation_params + path_item_params + security_params)
+          .map { |p| p["$ref"] ? resolve_parameter(p["$ref"], swagger_doc) : p }
+          .uniq { |p| p[:name] }
+          .reject { |p| p[:required] == false && !example.respond_to?(extract_getter(p)) }
+      end
+
+      def derive_security_params(metadata, swagger_doc)
+        requirements = metadata[:operation][:security] || swagger_doc[:security] || []
+        scheme_names = requirements.flat_map(&:keys)
+        schemes = security_version(scheme_names, swagger_doc)
+
+        schemes.map do |scheme|
+          param = scheme[:type] == :apiKey ? scheme.slice(:name, :in) : { name: "Authorization", in: :header }
+          param.merge(type: :string, required: requirements.one?)
+        end
+      end
+
+      def security_version(scheme_names, swagger_doc)
+        if doc_version(swagger_doc).start_with?("2")
+          (swagger_doc[:securityDefinitions] || {}).slice(*scheme_names).values
+        else # Openapi3
+          if swagger_doc.key?(:securityDefinitions)
+            RSpec::Swag.deprecator.warn("RSpec::Swag: WARNING: securityDefinitions is replaced in OpenAPI3! "\
+                                           "Rename to components/securitySchemes (in swagger_helper.rb)")
+            swagger_doc[:components] ||= { securitySchemes: swagger_doc[:securityDefinitions] }
+            swagger_doc.delete(:securityDefinitions)
+          end
+          components = swagger_doc[:components] || {}
+          (components[:securitySchemes] || {}).slice(*scheme_names).values
+        end
+      end
+
+      def resolve_parameter(ref, swagger_doc)
+        key = key_version(ref, swagger_doc)
+        definitions = definition_version(swagger_doc)
+        raise "Referenced parameter '#{ref}' must be defined" unless definitions && definitions[key]
+
+        definitions[key]
+      end
+
+      def key_version(ref, swagger_doc)
+        if doc_version(swagger_doc).start_with?("2")
+          ref.sub("#/parameters/", "").to_sym
+        elsif ref.start_with?("#/parameters/") # Openapi3
+          RSpec::Swag.deprecator.warn("RSpec::Swag: WARNING: #/parameters/ refs are replaced in OpenAPI3! " \
+                                          "Rename to #/components/parameters/")
+          ref.sub("#/parameters/", "").to_sym
+        else
+          ref.sub("#/components/parameters/", "").to_sym
+        end
+      end
+
+      def definition_version(swagger_doc)
+        if doc_version(swagger_doc).start_with?("2")
+          swagger_doc[:parameters]
+        elsif swagger_doc.key?(:parameters) # Openapi3
+          RSpec::Swag.deprecator.warn("RSpec::Swag: WARNING: parameters is replaced in OpenAPI3! "\
+                                          "Rename to components/parameters (in swagger_helper.rb)")
+          swagger_doc[:parameters]
+        else
+          components = swagger_doc[:components] || {}
+          components[:parameters]
+        end
+      end
+
+      def add_verb(request, metadata)
+        request[:verb] = metadata[:operation][:verb]
+      end
+
+      def base_path_from_servers(swagger_doc, use_server = :default)
+        return "" if swagger_doc[:servers].nil? || swagger_doc[:servers].empty?
+
+        server = swagger_doc[:servers].first
+        variables = {}
+        server.fetch(:variables, {}).each_pair { |k, v| variables[k] = v[use_server] }
+        base_path = server[:url].gsub(/\{(.*?)\}/) { variables[::Regexp.last_match(1).to_sym] }
+        URI(base_path).path
+      end
+
+      # rubocop:disable Metrics/AbcSize,Metrics/PerceivedComplexity
+      def add_path(request, metadata, swagger_doc, parameters, example)
+        open_api_3_doc = doc_version(swagger_doc).start_with?("3")
+        uses_base_path = swagger_doc[:basePath].present?
+
+        if open_api_3_doc && uses_base_path
+          RSpec::Swag.deprecator.warn("RSpec::Swag: WARNING: basePath is replaced in OpenAPI3! " \
+                                         "Update your swagger_helper.rb")
+        end
+
+        template = if uses_base_path
+                     (swagger_doc[:basePath] || "") + metadata[:path_item][:template]
+                   else # OpenAPI 3
+                     base_path_from_servers(swagger_doc) + metadata[:path_item][:template]
+                   end
+
+        request[:path] = template.tap do |path_template|
+          parameters.select { |p| p[:in] == :path }.each do |p|
+            unless example.respond_to?(extract_getter(p))
+              raise ArgumentError, "`#{p[:name]}` parameter key present, but not defined within example group" \
+                                   "(i. e `it` or `let` block)"
+            end
+            path_template.gsub!("{#{p[:name]}}", example.send(extract_getter(p)).to_s)
+          end
+
+          parameters.select { |p| p[:in] == :query }.each_with_index do |p, i|
+            path_template.concat(i.zero? ? "?" : "&")
+            path_template.concat(build_query_string_part(p, example.send(extract_getter(p)), swagger_doc))
+          end
+        end
+      end
+      # rubocop:enable all
+
+      # rubocop:disable Metrics/BlockNesting,Style/HashLikeCase,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/AbcSize,Metrics/PerceivedComplexity
+      def build_query_string_part(param, value, swagger_doc)
+        name = param[:name]
+        escaped_name = CGI.escape(name.to_s)
+
+        # OAS 3: https://swagger.io/docs/specification/serialization/
+        if swagger_doc && doc_version(swagger_doc).start_with?("3") && param[:schema]
+          style = param[:style]&.to_sym || :form
+          explode = param[:explode].nil? ? true : param[:explode]
+
+          case param[:schema][:type]&.to_sym
+          when :object
+            case style
+            when :deepObject
+              return { name => value }.to_query
+            when :form
+              return value.to_query if explode
+
+              return "#{escaped_name}=" + value.to_a.flatten.map { |v| CGI.escape(v.to_s) }.join(",")
+
+            end
+          when :array
+            case explode
+            when true
+              return value.to_a.flatten.map { |v| "#{escaped_name}=#{CGI.escape(v.to_s)}" }.join("&")
+            else
+              separator = case style
+                          when :form then ","
+                          when :spaceDelimited then "%20"
+                          when :pipeDelimited then "|"
+                          end
+              return "#{escaped_name}=" + value.to_a.flatten.map { |v| CGI.escape(v.to_s) }.join(separator)
+            end
+          else
+            return "#{name}=#{value}"
+          end
+        end
+
+        type = param[:type] || param.dig(:schema, :type)
+        return "#{escaped_name}=#{CGI.escape(value.to_s)}" unless type&.to_sym == :array
+
+        case param[:collectionFormat]
+        when :ssv
+          "#{name}=#{value.join(' ')}"
+        when :tsv
+          "#{name}=#{value.join('\t')}"
+        when :pipes
+          "#{name}=#{value.join('|')}"
+        when :multi
+          value.map { |v| "#{name}=#{v}" }.join("&")
+        else
+          "#{name}=#{value.join(',')}" # csv is default
+        end
+      end
+      # rubocop:enable all
+
+      # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+      def add_headers(request, metadata, swagger_doc, parameters, example)
+        tuples = parameters
+                   .select { |p| p[:in] == :header }
+                   .map { |p| [p[:name], example.send(extract_getter(p)).to_s] }
+
+        # Accept header
+        produces = metadata[:operation][:produces] || swagger_doc[:produces]
+        if produces
+          accept = example.respond_to?(:Accept) ? example.send(:Accept) : produces.first
+          tuples << ["Accept", accept]
+        end
+
+        # Content-Type header
+        consumes = metadata[:operation][:consumes] || swagger_doc[:consumes]
+        if consumes
+          content_type = example.respond_to?(:"Content-Type") ? example.send(:"Content-Type") : consumes.first
+          tuples << ["Content-Type", content_type]
+        end
+
+        # Host header
+        host = metadata[:operation][:host] || swagger_doc[:host]
+        if host.present?
+          host = example.respond_to?(:Host) ? example.send(:Host) : host
+          tuples << ["Host", host]
+        end
+
+        # Rails test infrastructure requires rack-formatted headers
+        rack_formatted_tuples = tuples.map do |pair|
+          [
+            case pair[0]
+            when "Accept" then "HTTP_ACCEPT"
+            when "Content-Type" then "CONTENT_TYPE"
+            when "Authorization" then "HTTP_AUTHORIZATION"
+            when "Host" then "HTTP_HOST"
+            else pair[0]
+            end,
+            pair[1]
+          ]
+        end
+
+        request[:headers] = Hash[rack_formatted_tuples]
+      end
+      # rubocop:enable all
+
+      def add_payload(request, parameters, example)
+        content_type = request[:headers]["CONTENT_TYPE"]
+        return if content_type.nil?
+
+        request[:payload] = if ["application/x-www-form-urlencoded", "multipart/form-data"].include?(content_type)
+                              build_form_payload(parameters, example)
+                            elsif content_type == "application/json"
+                              build_json_payload(parameters, example)
+                            else
+                              build_raw_payload(parameters, example)
+                            end
+      end
+
+      def build_form_payload(parameters, example)
+        # See http://seejohncode.com/2012/04/29/quick-tip-testing-multipart-uploads-with-rspec/
+        # Rather that serializing with the appropriate encoding (e.g. multipart/form-data),
+        # Rails test infrastructure allows us to send the values directly as a hash
+        # PROS: simple to implement, CONS: serialization/deserialization is bypassed in test
+        tuples = parameters
+                   .select { |p| p[:in] == :formData }
+                   .map { |p| [p[:name], example.send(extract_getter(p))] }
+        Hash[tuples]
+      end
+
+      def build_raw_payload(parameters, example)
+        body_param = parameters.select { |p| p[:in] == :body }.first
+        return nil unless body_param
+
+        raise(MissingParameterError, body_param[:name]) unless example.respond_to?(body_param[:name])
+
+        example.send(body_param[:name])
+      end
+
+      def build_json_payload(parameters, example)
+        build_raw_payload(parameters, example)&.to_json
+      end
+
+      def doc_version(doc)
+        doc[:openapi] || doc[:swagger] || "3"
+      end
+
+      def extract_getter(parameter)
+        parameter[:getter] || parameter[:name]
+      end
+    end
+
+    class MissingParameterError < StandardError
+      def message
+        <<~MSG
+          Missing parameter '#{super}'
+
+          Please check your spec. It looks like you defined a body parameter,
+          but did not declare usage via let. Try adding:
+
+              let(:#{super}) {}
+        MSG
+      end
+    end
+  end
+end

data/lib/rspec/swag/response_validator.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/slice"
+require "json-schema"
+require "json"
+require "rspec/swag/extended_schema"
+
+module RSpec
+  module Swag
+    class ResponseValidator
+      def initialize(config = ::RSpec::Swag.config)
+        @config = config
+      end
+
+      def validate!(metadata, response)
+        swagger_doc = @config.get_openapi_spec(metadata[:openapi_spec] || metadata[:swagger_doc])
+
+        validate_code!(metadata, response)
+        validate_headers!(metadata, response.headers)
+        validate_body!(metadata, swagger_doc, response.body)
+      end
+
+      private
+
+      def validate_code!(metadata, response)
+        expected = metadata[:response][:code].to_s
+        return unless response.status.to_s != expected
+
+        raise UnexpectedResponse,
+              "Expected response code '#{response.status}' to match '#{expected}'\n" \
+              "Response body: #{response.body}"
+      end
+
+      # rubocop:disable Metrics/PerceivedComplexity
+      def validate_headers!(metadata, headers)
+        header_schemas = metadata[:response][:headers] || {}
+        expected = header_schemas.keys
+        expected.each do |name|
+          nullable_attribute = header_schemas.dig(name.to_s, :schema, :nullable)
+          required_attribute = header_schemas.dig(name.to_s, :required)
+
+          is_nullable = nullable_attribute.nil? ? false : nullable_attribute
+          is_required = required_attribute.nil? ? true : required_attribute
+
+          if !headers.include?(name.to_s) && is_required
+            raise UnexpectedResponse, "Expected response header #{name} to be present"
+          end
+
+          if headers.include?(name.to_s) && headers[name.to_s].nil? && !is_nullable
+            raise UnexpectedResponse, "Expected response header #{name} to not be null"
+          end
+        end
+      end
+      # rubocop:enable Metrics/PerceivedComplexity
+
+      def validate_body!(metadata, swagger_doc, body)
+        response_schema = metadata[:response][:schema]
+        return if response_schema.nil?
+
+        version = @config.get_openapi_spec_version(metadata[:openapi_spec] || metadata[:swagger_doc])
+        schemas = definitions_or_component_schemas(swagger_doc, version)
+
+        validation_schema = response_schema
+                              .merge("$schema" => "http://tempuri.org/rswag/specs/extended_schema")
+                              .merge(schemas)
+
+        validation_options = validation_options_from(metadata)
+
+        errors = JSON::Validator.fully_validate(validation_schema, body, validation_options)
+        return unless errors.any?
+
+        raise UnexpectedResponse,
+              "Expected response body to match schema: #{errors.join("\n")}\n" \
+              "Response body: #{JSON.pretty_generate(JSON.parse(body))}"
+      end
+
+      # rubocop:disable Style/DoubleNegation
+      def validation_options_from(metadata)
+        is_strict = !!metadata.fetch(:openapi_strict_schema_validation, @config.openapi_strict_schema_validation)
+
+        { strict: is_strict }
+      end
+      # rubocop:enable Style/DoubleNegation
+
+      def definitions_or_component_schemas(swagger_doc, version)
+        if version.start_with?("2")
+          swagger_doc.slice(:definitions)
+        elsif swagger_doc.key?(:definitions) # Openapi3
+          RSpec::Swag.deprecator.warn("RSpec::Swag: WARNING: definitions is replaced in OpenAPI3! "\
+                                         "Rename to components/schemas (in swagger_helper.rb)")
+          swagger_doc.slice(:definitions)
+        else
+          components = swagger_doc[:components] || {}
+          { components: components }
+        end
+      end
+    end
+
+    class UnexpectedResponse < StandardError; end
+  end
+end

data/lib/rspec/swag/swagger_formatter.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/deep_merge"
+require "rspec/core/formatters/base_text_formatter"
+require "swagger_helper"
+
+module RSpec
+  module Swag
+    # rubocop:disable Metrics/ClassLength
+    class SwaggerFormatter < ::RSpec::Core::Formatters::BaseTextFormatter
+      ::RSpec::Core::Formatters.register self, :example_group_finished, :stop
+
+      def initialize(output, config = RSpec::Swag.config)
+        super(output)
+        @config = config
+
+        @output.puts "Generating Swagger docs ..."
+      end
+
+      def example_group_finished(notification)
+        metadata = notification.group.metadata
+
+        # !metadata[:document] won't work, since nil means we should generate docs.
+        return if metadata[:document] == false
+        return unless metadata.key?(:response)
+
+        swagger_doc = @config.get_openapi_spec(metadata[:openapi_spec] || metadata[:swagger_doc])
+
+        unless doc_version(swagger_doc).start_with?("2")
+          # This is called multiple times per file!
+          # metadata[:operation] is also re-used between examples within file
+          # therefore be careful NOT to modify its content here.
+          upgrade_request_type!(metadata)
+          upgrade_servers!(swagger_doc)
+          upgrade_oauth!(swagger_doc)
+          upgrade_response_produces!(swagger_doc, metadata)
+        end
+
+        swagger_doc.deep_merge!(metadata_to_swagger(metadata))
+      end
+
+      # rubocop:disable all
+      def stop(_notification = nil)
+        @config.openapi_specs.each do |url_path, doc|
+          unless doc_version(doc).start_with?("2")
+            doc[:paths]&.each_pair do |_k, v|
+              v.each_pair do |_verb, value|
+                is_hash = value.is_a?(Hash)
+                if is_hash && value[:parameters]
+                  schema_param = value[:parameters]&.find { |p| (p[:in] == :body || p[:in] == :formData) && p[:schema] }
+                  mime_list = value[:consumes] || doc[:consumes]
+
+                  if value && schema_param && mime_list
+                    value[:requestBody] = { content: {} } unless value.dig(:requestBody, :content)
+                    value[:requestBody][:required] = true if schema_param[:required]
+                    value[:requestBody][:description] = schema_param[:description] if schema_param[:description]
+                    examples = value[:request_examples]
+                    mime_list.each do |mime|
+                      value[:requestBody][:content][mime] = { schema: schema_param[:schema] }
+                      next unless examples
+
+                      value[:requestBody][:content][mime][:examples] ||= {}
+                      examples.map do |example|
+                        value[:requestBody][:content][mime][:examples][example[:name]] = {
+                          summary: example[:summary] || value[:summary],
+                          value: example[:value]
+                        }
+                      end
+                    end
+                  end
+
+                  value[:parameters].reject! { |p| p[:in] == :body || p[:in] == :formData }
+                end
+                remove_invalid_operation_keys!(value)
+              end
+            end
+          end
+
+          file_path = File.join(@config.openapi_root, url_path)
+          dirname = File.dirname(file_path)
+          FileUtils.mkdir_p dirname unless File.exist?(dirname)
+
+          File.open(file_path, "w") do |file|
+            file.write(pretty_generate(doc))
+          end
+
+          @output.puts "Swagger doc generated at #{file_path}"
+        end
+      end
+      # rubocop:enable all
+
+      private
+
+      def pretty_generate(doc)
+        if @config.openapi_format == :yaml
+          clean_doc = yaml_prepare(doc)
+          YAML.dump(clean_doc)
+        else # config errors are thrown in 'def openapi_format', no throw needed here
+          JSON.pretty_generate(doc)
+        end
+      end
+
+      def yaml_prepare(doc)
+        json_doc = JSON.pretty_generate(doc)
+        JSON.parse(json_doc)
+      end
+
+      def metadata_to_swagger(metadata)
+        response_code = metadata[:response][:code]
+        response = metadata[:response].reject { |k, _v| k == :code }
+
+        verb = metadata[:operation][:verb]
+        operation = metadata[:operation]
+                      .reject { |k, _v| k == :verb }
+                      .merge(responses: { response_code => response })
+
+        path_template = metadata[:path_item][:template]
+        path_item = metadata[:path_item]
+                      .reject { |k, _v| k == :template }
+                      .merge(verb => operation)
+
+        { paths: { path_template => path_item } }
+      end
+
+      def doc_version(doc)
+        doc[:openapi] || doc[:swagger] || "3"
+      end
+
+      def upgrade_response_produces!(swagger_doc, metadata)
+        # Accept header
+        mime_list = Array(metadata[:operation][:produces] || swagger_doc[:produces])
+        target_node = metadata[:response]
+        upgrade_content!(mime_list, target_node)
+        metadata[:response].delete(:schema)
+      end
+
+      def upgrade_content!(mime_list, target_node)
+        schema = target_node[:schema]
+        return if mime_list.empty? || schema.nil?
+
+        target_node[:content] ||= {}
+        mime_list.each do |mime_type|
+          # TODO: upgrade to have content-type specific schema
+          (target_node[:content][mime_type] ||= {}).merge!(schema: schema)
+        end
+      end
+
+      def upgrade_request_type!(metadata)
+        # No deprecation here as it seems valid to allow type as a shorthand
+        operation_nodes = metadata[:operation][:parameters] || []
+        path_nodes = metadata[:path_item][:parameters] || []
+        header_node = metadata[:response][:headers] || {}
+
+        (operation_nodes + path_nodes + [header_node]).each do |node|
+          if node && node[:type] && node[:schema].nil?
+            node[:schema] = { type: node[:type] }
+            node.delete(:type)
+          end
+        end
+      end
+
+      def upgrade_servers!(swagger_doc)
+        return unless swagger_doc[:servers].nil? && swagger_doc.key?(:schemes)
+
+        RSpec::Swag.deprecator.warn("RSpec::Swag: WARNING: schemes, host, and basePath are replaced " \
+                                       "in OpenAPI3! Rename to array of servers[{url}] (in swagger_helper.rb)")
+
+        swagger_doc[:servers] = { urls: [] }
+        swagger_doc[:schemes].each do |scheme|
+          swagger_doc[:servers][:urls] << "#{scheme}://#{swagger_doc[:host]}#{swagger_doc[:basePath]}"
+        end
+
+        swagger_doc.delete(:schemes)
+        swagger_doc.delete(:host)
+        swagger_doc.delete(:basePath)
+      end
+
+      # rubocop:disable all
+      def upgrade_oauth!(swagger_doc)
+        # find flow in securitySchemes (securityDefinitions will have been re-written)
+        schemes = swagger_doc.dig(:components, :securitySchemes)
+        return unless schemes&.any? { |_k, v| v.key?(:flow) }
+
+        schemes.each do |name, v|
+          next unless v.key?(:flow)
+
+          RSpec::Swag.deprecator.warn("RSpec::Swag: WARNING: securityDefinitions flow is replaced in OpenAPI3! " \
+                                         "Rename to components/securitySchemes/#{name}/flows[] (in swagger_helper.rb)")
+          flow = swagger_doc[:components][:securitySchemes][name].delete(:flow).to_s
+          if flow == "accessCode"
+            RSpec::Swag.deprecator.warn("RSpec::Swag: WARNING: securityDefinitions accessCode is replaced " \
+                                           "in OpenAPI3! Rename to clientCredentials (in swagger_helper.rb)")
+            flow = "authorizationCode"
+          end
+          if flow == "application"
+            RSpec::Swag.deprecator.warn("RSpec::Swag: WARNING: securityDefinitions application is replaced " \
+                                           "in OpenAPI3! Rename to authorizationCode (in swagger_helper.rb)")
+            flow = "clientCredentials"
+          end
+          flow_elements = swagger_doc[:components][:securitySchemes][name].except(:type).each_with_object({}) do |(k, _v), a|
+            a[k] = swagger_doc[:components][:securitySchemes][name].delete(k)
+          end
+          swagger_doc[:components][:securitySchemes][name].merge!(flows: { flow => flow_elements })
+        end
+      end
+      # rubocop:enable all
+
+      def remove_invalid_operation_keys!(value)
+        return unless value.is_a?(Hash)
+
+        value&.delete(:consumes)
+        value&.delete(:produces)
+        value&.delete(:request_examples)
+        value[:parameters]&.each { |p| p.delete(:getter) }
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/rspec/swag/tasks/rspec_swag_tasks.rake

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rspec/swag"
+require "rspec/core/rake_task"
+require "rspec/swag/project_initializer"
+
+namespace :rspec do
+  desc "Generate Swagger JSON files from integration specs"
+  RSpec::Core::RakeTask.new("swaggerize") do |t|
+    t.pattern = ENV.fetch(
+      "PATTERN",
+      "spec/requests/**/*_spec.rb, spec/api/**/*_spec.rb, spec/integration/**/*_spec.rb"
+    )
+
+    additional_rspec_opts = ENV.fetch(
+      "ADDITIONAL_RSPEC_OPTS",
+      ""
+    )
+
+    t.rspec_opts = [additional_rspec_opts]
+
+    t.rspec_opts += if RSpec::Swag.config.swagger_dry_run
+                      ["--format RSpec::Swag::SwaggerFormatter", "--dry-run", "--order defined"]
+                    else
+                      ["--format RSpec::Swag::SwaggerFormatter", "--order defined"]
+                    end
+  end
+
+  namespace :swag do
+    desc "Copy swagger_helper.rb to spec/"
+    task :install do
+      RSpec::Swag::ProjectInitializer.new.run
+    end
+  end
+end
+
+task swaggerize: ["rspec:swaggerize"]

data/lib/rspec/swag/templates/spec/swagger_helper.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "rspec/swag"
+
+RSpec.configure do |config|
+  # Specify a root folder where Swagger JSON files are generated
+  # NOTE: If you're using the rswag-api to serve API descriptions, you'll need
+  # to ensure that it's configured to serve Swagger from the same folder
+  config.openapi_root = File.expand_path("../", File.dirname(__FILE__))
+
+  # Define one or more Swagger documents and provide global metadata for each one
+  # When you run the 'rspec:swaggerize' rake task, the complete Swagger will
+  # be generated at the provided relative path under openapi_root
+  # By default, the operations defined in spec files are added to the first
+  # document below. You can override this behavior by adding a openapi_spec tag to the
+  # the root example_group in your specs, e.g. describe '...', openapi_spec: 'v2/swagger.json'
+  config.openapi_specs = {
+    "v1/swagger.yaml" => {
+      openapi: "3.0.1",
+      info: {
+        title: "API V1",
+        version: "v1"
+      },
+      paths: {},
+      servers: [
+        {
+          url: "{protocol}://{host}:{port}",
+          variables: {
+            protocol: {
+              enum: ["http", "https"],
+              default: "http"
+            },
+            host: {
+              default: "localhost"
+            },
+            port: {
+              default: "3000"
+            }
+          }
+        }
+      ]
+    }
+  }
+
+  # Specify the format of the output Swagger file when running 'rspec:swaggerize'.
+  # The openapi_specs configuration option has the filename including format in
+  # the key, this may want to be changed to avoid putting yaml in json files.
+  # Defaults to json. Accepts ':json' and ':yaml'.
+  config.openapi_format = :yaml
+end

data/lib/rspec/swag/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Swag
+    VERSION = "0.1.2"
+  end
+end

data/lib/rspec/swag.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require "rspec/swag/example_group_helpers"
+require "rspec/swag/example_helpers"
+require "rspec/swag/configuration"
+
+module RSpec
+  module Swag
+    # Extend RSpec with a swagger-based DSL
+    ::RSpec.configure do |c|
+      c.add_setting :openapi_root
+      c.add_setting :openapi_specs
+      c.add_setting :swagger_dry_run
+      c.add_setting :openapi_format, default: :json
+      c.add_setting :openapi_strict_schema_validation
+      c.extend ExampleGroupHelpers
+      c.include ExampleHelpers
+    end
+
+    def self.config
+      @config ||= Configuration.new(RSpec.configuration)
+    end
+
+    def self.deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new("3.0", "rspec-swag")
+    end
+  end
+end

metadata

@@ -0,0 +1,187 @@
+--- !ruby/object:Gem::Specification
+name: rspec-swag
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Richie Morris
+- Greg Myers
+- Jay Danielian
+- GracefulPotato
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-02-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.13.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.13.0
+- !ruby/object:Gem::Dependency
+  name: climate_control
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.60.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.60.2
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.21.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.21.2
+description: 'Simplify API integration testing with a succinct rspec DSL and generate
+  OpenAPI specification files directly from your rspec tests. More about the OpenAPI
+  initiative here: http://spec.openapis.org/'
+email:
+- gracefulpotatow@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop_rspec_alias_config.yml"
+- MIT-LICENSE
+- Rakefile
+- lib/rspec/swag.rb
+- lib/rspec/swag/configuration.rb
+- lib/rspec/swag/example_group_helpers.rb
+- lib/rspec/swag/example_helpers.rb
+- lib/rspec/swag/extended_schema.rb
+- lib/rspec/swag/project_initializer.rb
+- lib/rspec/swag/rake_task.rb
+- lib/rspec/swag/request_factory.rb
+- lib/rspec/swag/response_validator.rb
+- lib/rspec/swag/swagger_formatter.rb
+- lib/rspec/swag/tasks/rspec_swag_tasks.rake
+- lib/rspec/swag/templates/spec/swagger_helper.rb
+- lib/rspec/swag/version.rb
+homepage: https://github.com/graceful-potato/rspec-swag
+licenses:
+- MIT
+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: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: An OpenAPI-based (formerly called Swagger) DSL for rspec & accompanying rake
+  task for generating OpenAPI specification files
+test_files: []