miniswag 0.1.0

data/lib/miniswag/openapi_generator.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/deep_merge'
+require 'json'
+require 'yaml'
+require 'fileutils'
+
+module Miniswag
+  # Collects metadata from test definitions and generates OpenAPI spec files.
+  # This is the Minitest equivalent of rswag's OpenapiFormatter.
+  class OpenapiGenerator
+    def initialize(config = Miniswag.config)
+      @config = config
+    end
+
+    def generate!
+      @config.validate!
+
+      # Process all registered test class metadata
+      Miniswag.registered_test_classes.each do |test_class|
+        test_class.miniswag_test_definitions.each do |metadata|
+          next if metadata[:document] == false
+          next unless metadata.key?(:response)
+
+          openapi_spec = @config.get_openapi_spec(metadata[:openapi_spec])
+          raise ConfigurationError, 'Unsupported OpenAPI version' unless doc_version(openapi_spec)&.start_with?('3')
+
+          upgrade_request_type!(metadata)
+          upgrade_response_produces!(openapi_spec, metadata)
+          openapi_spec.deep_merge!(metadata_to_openapi(metadata))
+        end
+      end
+
+      # Post-process and write files
+      @config.openapi_specs.each do |url_path, doc|
+        parse_parameters(doc)
+        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
+        puts "Miniswag: OpenAPI doc generated at #{file_path}"
+      end
+    end
+
+    private
+
+    def doc_version(doc)
+      doc[:openapi]
+    end
+
+    def pretty_generate(doc)
+      if @config.openapi_format == :yaml
+        clean_doc = JSON.parse(JSON.pretty_generate(doc))
+        YAML.dump(clean_doc)
+      else
+        JSON.pretty_generate(doc)
+      end
+    end
+
+    def metadata_to_openapi(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 upgrade_response_produces!(openapi_spec, metadata)
+      mime_list = Array(metadata[:operation][:produces] || openapi_spec[: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|
+        (target_node[:content][mime_type] ||= {}).merge!(schema: schema)
+      end
+    end
+
+    def upgrade_request_type!(metadata)
+      operation_nodes = metadata[:operation][:parameters] || []
+      path_nodes = metadata[:path_item][:parameters] || []
+      header_node = metadata[:response][:headers] || {}
+      (operation_nodes + path_nodes + header_node.values).each do |node|
+        if node && node[:type] && node[:schema].nil?
+          node[:schema] = { type: node[:type] }
+          node.delete(:type)
+        end
+      end
+    end
+
+    def remove_invalid_operation_keys!(value)
+      return unless value.is_a?(Hash)
+
+      value.delete(:consumes) if value[:consumes]
+      value.delete(:produces) if value[:produces]
+      value.delete(:request_examples) if value[:request_examples]
+    end
+
+    def parse_parameters(doc)
+      doc[:paths]&.each_pair do |_k, path|
+        path.each_pair do |_verb, endpoint|
+          is_hash = endpoint.is_a?(Hash)
+          if is_hash && endpoint[:parameters]
+            mime_list = endpoint[:consumes] || doc[:consumes]
+            parse_endpoint(endpoint, mime_list)
+          end
+          remove_invalid_operation_keys!(endpoint)
+        end
+      end
+    end
+
+    def parse_endpoint(endpoint, mime_list)
+      parameters = endpoint[:parameters]
+      parameters.each do |parameter|
+        set_parameter_schema(parameter)
+        convert_file_parameter(parameter)
+        parse_enum(parameter)
+      end
+      parameters.select { |p| parameter_in_form_data_or_body?(p) }.each do |parameter|
+        parse_form_data_or_body_parameter(endpoint, parameter, mime_list)
+        parameters.delete(parameter)
+      end
+      parameters.each { |p| p.delete(:schema) if p[:schema].blank? }
+    end
+
+    def set_parameter_schema(parameter)
+      parameter[:schema] ||= {}
+      if parameter[:schema].key?(:required) && parameter[:schema][:required] == true
+        parameter[:required] = parameter[:schema].delete(:required)
+      end
+      parameter[:schema][:type] = parameter.delete(:type) if parameter.key?(:type)
+    end
+
+    def parameter_in_form_data_or_body?(p)
+      p[:in] == :formData || parameter_in_body?(p)
+    end
+
+    def parameter_in_body?(p)
+      p[:in] == :body
+    end
+
+    def parse_form_data_or_body_parameter(endpoint, parameter, mime_list)
+      unless mime_list
+        raise ConfigurationError,
+              'A body or form data parameters are specified without a Media Type for the content'
+      end
+      add_request_body(endpoint)
+      desc = parameter.delete(:description)
+      parameter[:schema][:description] = desc if desc
+      mime_list.each do |mime|
+        endpoint[:requestBody][:content][mime] ||= {}
+        mime_config = endpoint[:requestBody][:content][mime]
+        next unless mime_config[:schema].nil? || mime_config.dig(:schema, :properties)
+
+        set_mime_config(mime_config, parameter)
+        set_mime_examples(mime_config, endpoint)
+        set_request_body_required(mime_config, endpoint, parameter)
+      end
+    end
+
+    def add_request_body(endpoint)
+      return if endpoint.dig(:requestBody, :content)
+
+      endpoint[:requestBody] = { content: {} }
+    end
+
+    def set_request_body_required(mime_config, endpoint, parameter)
+      return unless parameter[:required]
+
+      endpoint[:requestBody][:required] = true
+      return if parameter_in_body?(parameter)
+
+      if parameter[:name]
+        mime_config[:schema][:required] ||= []
+        mime_config[:schema][:required] << parameter[:name].to_s
+      else
+        mime_config[:schema][:required] = true
+      end
+    end
+
+    def convert_file_parameter(parameter)
+      return unless parameter[:schema][:type] == :file
+
+      parameter[:schema][:type] = :string
+      parameter[:schema][:format] = :binary
+    end
+
+    def set_mime_config(mime_config, parameter)
+      schema_with_form_properties = parameter[:name] && !parameter_in_body?(parameter)
+      mime_config[:schema] ||= schema_with_form_properties ? { type: :object, properties: {} } : parameter[:schema]
+      return unless schema_with_form_properties
+
+      mime_config[:schema][:properties][parameter[:name]] = parameter[:schema]
+      set_mime_encoding(mime_config, parameter)
+    end
+
+    def set_mime_encoding(mime_config, parameter)
+      return unless parameter[:encoding]
+
+      encoding = parameter[:encoding].dup
+      encoding[:contentType] = encoding[:contentType].join(',') if encoding[:contentType].is_a?(Array)
+      mime_config[:encoding] ||= {}
+      mime_config[:encoding][parameter[:name]] = encoding
+    end
+
+    def set_mime_examples(mime_config, endpoint)
+      examples = endpoint[:request_examples]
+      return unless examples
+
+      examples.each do |ex|
+        mime_config[:examples] ||= {}
+        mime_config[:examples][ex[:name]] = {
+          summary: ex[:summary] || endpoint[:summary],
+          value: ex[:value]
+        }
+      end
+    end
+
+    def parse_enum(parameter)
+      return unless parameter.key?(:enum)
+
+      enum = parameter.delete(:enum)
+      parameter[:schema] ||= {}
+      parameter[:schema][:enum] = enum.is_a?(Hash) ? enum.keys.map(&:to_s) : enum
+      parameter[:description] = generate_enum_description(parameter, enum) if enum.is_a?(Hash)
+    end
+
+    def generate_enum_description(param, enum)
+      enum_description = "#{param[:description]}:\n "
+      enum.each do |k, v|
+        enum_description += "* `#{k}` #{v}\n "
+      end
+      enum_description
+    end
+  end
+end

data/lib/miniswag/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Miniswag
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      load File.expand_path('../tasks/miniswag_tasks.rake', __dir__)
+    end
+
+    generators do
+      require 'generators/miniswag/install/install_generator'
+    end
+  end
+end

data/lib/miniswag/request_factory.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/hash/slice'
+require 'active_support/core_ext/hash/conversions'
+require 'json'
+require 'cgi'
+
+module Miniswag
+  class RequestFactory
+    attr_accessor :metadata, :params, :headers
+
+    def initialize(metadata, params = {}, headers = {}, config = Miniswag.config)
+      @config = config
+      @metadata = metadata
+      @params = params.transform_keys(&:to_s)
+      @headers = headers.transform_keys(&:to_s)
+    end
+
+    def build_request
+      openapi_spec = @config.get_openapi_spec(metadata[:openapi_spec])
+      parameters = expand_parameters(metadata, openapi_spec)
+      {}.tap do |request|
+        add_verb(request, metadata)
+        add_path(request, metadata, openapi_spec, parameters)
+        add_headers(request, metadata, openapi_spec, parameters)
+        add_payload(request, parameters)
+      end
+    end
+
+    private
+
+    def expand_parameters(metadata, openapi_spec)
+      operation_params = metadata[:operation][:parameters] || []
+      path_item_params = metadata[:path_item][:parameters] || []
+      security_params = derive_security_params(metadata, openapi_spec)
+      (operation_params + path_item_params + security_params)
+        .map { |p| p['$ref'] ? resolve_parameter(p['$ref'], openapi_spec) : p }
+        .uniq { |p| p[:name] }
+        .reject do |p|
+          p[:required] == false &&
+            !@headers.key?(p[:name].to_s) &&
+            !@params.key?(p[:name].to_s)
+        end
+    end
+
+    def derive_security_params(metadata, openapi_spec)
+      requirements = metadata[:operation][:security] || openapi_spec[:security] || []
+      scheme_names = requirements.flat_map(&:keys)
+      schemes = security_version(scheme_names, openapi_spec)
+      schemes.map do |scheme|
+        param = scheme[:type] == :apiKey ? scheme.slice(:name, :in) : { name: 'Authorization', in: :header }
+        param.merge(schema: { type: :string }, required: requirements.one?)
+      end
+    end
+
+    def security_version(scheme_names, openapi_spec)
+      components = openapi_spec[:components] || {}
+      (components[:securitySchemes] || {}).slice(*scheme_names).values
+    end
+
+    def resolve_parameter(ref, openapi_spec)
+      key = ref.sub('#/components/parameters/', '').to_sym
+      definitions = (openapi_spec[:components] || {})[:parameters]
+      raise "Referenced parameter '#{ref}' must be defined" unless definitions && definitions[key]
+
+      definitions[key]
+    end
+
+    def add_verb(request, metadata)
+      request[:verb] = metadata[:operation][:verb]
+    end
+
+    def base_path_from_servers(openapi_spec, use_server = :default)
+      return '' if openapi_spec[:servers].nil? || openapi_spec[:servers].empty?
+
+      server = openapi_spec[: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
+
+    def add_path(request, metadata, openapi_spec, parameters)
+      template = base_path_from_servers(openapi_spec) + metadata[:path_item][:template]
+      request[:path] = template.tap do |path_template|
+        parameters.select { |p| p[:in] == :path }.each do |p|
+          param_value = @params.fetch(p[:name].to_s) do
+            raise ArgumentError, "`#{p[:name]}` parameter key present in path but not provided in params"
+          end
+          path_template.gsub!("{#{p[:name]}}", param_value.to_s)
+        end
+        parameters.select { |p| p[:in] == :query && @params.key?(p[:name].to_s) }.each_with_index do |p, i|
+          path_template.concat(i.zero? ? '?' : '&')
+          path_template.concat(build_query_string_part(p, @params.fetch(p[:name].to_s), openapi_spec))
+        end
+      end
+    end
+
+    def build_query_string_part(param, value, _openapi_spec)
+      name = param[:name]
+      escaped_name = CGI.escape(name.to_s)
+      return unless param[:schema]
+
+      style = param[:style]&.to_sym || :form
+      explode = param[:explode].nil? || param[:explode]
+      type = param.dig(:schema, :type)&.to_sym
+      case type
+      when :object
+        case style
+        when :deepObject then { name => value }.to_query
+        when :form
+          return value.to_query if explode
+
+          "#{escaped_name}=" + value.to_a.flatten.map { |v| CGI.escape(v.to_s) }.join(',')
+        end
+      when :array
+        case explode
+        when true
+          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
+          "#{escaped_name}=" + value.to_a.flatten.map { |v| CGI.escape(v.to_s) }.join(separator)
+        end
+      else
+        "#{escaped_name}=#{CGI.escape(value.to_s)}"
+      end
+    end
+
+    def add_headers(request, metadata, openapi_spec, parameters)
+      tuples = parameters
+               .select { |p| p[:in] == :header }
+               .map { |p| [p[:name], @headers.fetch(p[:name].to_s, '').to_s] }
+
+      produces = metadata[:operation][:produces] || openapi_spec[:produces]
+      if produces
+        accept = @headers.fetch('Accept', produces.first)
+        tuples << ['Accept', accept]
+      end
+
+      consumes = metadata[:operation][:consumes] || openapi_spec[:consumes]
+      if consumes
+        content_type = @headers.fetch('Content-Type', consumes.first)
+        tuples << ['Content-Type', content_type]
+      end
+
+      host = metadata[:operation][:host] || openapi_spec[:host]
+      tuples << ['Host', host] if host.present?
+
+      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
+
+    def add_payload(request, parameters)
+      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)
+                          elsif %r{\Aapplication/([0-9A-Za-z._-]+\+json\z|json\z)}.match?(content_type)
+                            build_json_payload(parameters)
+                          else
+                            build_raw_payload(parameters)
+                          end
+    end
+
+    def build_form_payload(parameters)
+      tuples = parameters
+               .select { |p| p[:in] == :formData }
+               .map { |p| [p[:name], @params.fetch(p[:name].to_s)] }
+      Hash[tuples]
+    end
+
+    def build_raw_payload(parameters)
+      body_param = parameters.find { |p| p[:in] == :body }
+      return nil unless body_param
+
+      @params.fetch(body_param[:name].to_s) do
+        raise MissingParameterError, body_param[:name]
+      end
+    end
+
+    def build_json_payload(parameters)
+      build_raw_payload(parameters)&.to_json
+    end
+  end
+
+  class MissingParameterError < StandardError
+    attr_reader :body_param
+
+    def initialize(body_param)
+      @body_param = body_param
+    end
+
+    def message
+      <<~MSG
+        Missing parameter '#{body_param}'
+        Please check your test. Ensure you provide the parameter in a `params` block.
+      MSG
+    end
+  end
+end

data/lib/miniswag/response_validator.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/enumerable'
+require 'active_support/core_ext/hash/slice'
+require 'json-schema'
+require 'json'
+require 'miniswag/extended_schema'
+
+module Miniswag
+  class ResponseValidator
+    def initialize(config = Miniswag.config)
+      @config = config
+    end
+
+    def validate!(metadata, response)
+      openapi_spec = @config.get_openapi_spec(metadata[:openapi_spec])
+      validate_code!(metadata, response)
+      validate_headers!(metadata, response.headers)
+      validate_body!(metadata, openapi_spec, response.body)
+    end
+
+    private
+
+    def validate_code!(metadata, response)
+      expected = metadata[:response][:code].to_s
+      return unless response.code != expected
+
+      raise UnexpectedResponse,
+            "Expected response code '#{response.code}' to match '#{expected}'\n" \
+              "Response body: #{response.body}"
+    end
+
+    def validate_headers!(metadata, headers)
+      header_schemas = metadata[:response][:headers] || {}
+      header_schemas.keys.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? || 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
+
+    def validate_body!(metadata, openapi_spec, body)
+      response_schema = metadata[:response][:schema]
+      return if response_schema.nil?
+
+      schemas = { components: openapi_spec[:components] }
+      validation_schema = response_schema
+                          .merge('$schema' => 'http://tempuri.org/miniswag/extended_schema')
+                          .merge(schemas)
+      validation_options = {
+        allPropertiesRequired: metadata.fetch(:openapi_all_properties_required,
+                                              @config.openapi_all_properties_required),
+        noAdditionalProperties: metadata.fetch(:openapi_no_additional_properties,
+                                               @config.openapi_no_additional_properties)
+      }
+      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
+  end
+
+  class UnexpectedResponse < StandardError; end
+end

data/lib/miniswag/test_case.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'action_dispatch/testing/integration'
+require 'miniswag/dsl'
+require 'miniswag/request_factory'
+require 'miniswag/response_validator'
+
+module Miniswag
+  class TestCase < ActionDispatch::IntegrationTest
+    extend DSL
+
+    class << self
+      # Returns all test definitions registered via run_test! for OpenAPI generation
+      def miniswag_test_definitions
+        @_miniswag_test_definitions || []
+      end
+    end
+  end
+end

data/lib/miniswag/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Miniswag
+  VERSION = '0.1.0'
+end

data/lib/miniswag.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'miniswag/version'
+require 'miniswag/configuration'
+require 'miniswag/railtie' if defined?(Rails::Railtie)
+
+module Miniswag
+  class << self
+    def configure
+      yield(config)
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Reset configuration (useful for testing)
+    def reset!
+      @config = nil
+      @registered_test_classes = nil
+    end
+
+    # Registry of test classes that have miniswag test definitions.
+    # Used by OpenapiGenerator to collect all metadata.
+    def register_test_class(klass)
+      registered_test_classes << klass unless registered_test_classes.include?(klass)
+    end
+
+    def registered_test_classes
+      @registered_test_classes ||= []
+    end
+  end
+end

data/lib/tasks/miniswag_tasks.rake

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+namespace :miniswag do
+  desc 'Generate OpenAPI spec files from Minitest integration tests'
+  task swaggerize: :environment do
+    pattern = ENV.fetch('PATTERN', 'test/integration/**/*_test.rb')
+    additional_opts = ENV.fetch('ADDITIONAL_OPTS', '')
+
+    # Set the env var so the minitest plugin activates
+    ENV['MINISWAG_GENERATE'] = '1'
+
+    # Require the openapi_helper which configures Miniswag
+    helper_path = Rails.root.join('test', 'openapi_helper.rb')
+    require helper_path.to_s if File.exist?(helper_path)
+
+    # Run minitest with the matching pattern
+    args = [
+      'bin/rails', 'test',
+      *Dir.glob(pattern),
+      additional_opts.presence
+    ].compact
+
+    system(*args) || abort('Miniswag: Test run failed')
+  end
+end
+
+task miniswag: ['miniswag:swaggerize']