rc-minitest-openapi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dc9be68f3e6661181cebec8f0470921dc0a94d4f5692d31d83b6e5ebb956c6fd
+  data.tar.gz: aae8e8280d8668d86fcddf48fd505ba225b10468b1b1cd4aaa511c3e7209e216
+SHA512:
+  metadata.gz: 70227955c8d7e173818dcc119dcedc28e1eaaec110991a1915ea30672f20c81f617e39d08b8d1f130dfe6ddcc06104ee8d7b9bd1005ec306c5b1ca019a4cd343
+  data.tar.gz: 2f06ed50395e49d2039fe8a43a16e2cad2a210fff0dde93bafc7a0e0ea50db2e3284ac0eef35b5563ec7ae741dd31f176885b643026586d1291eef3b32ab0707

data/README.md

@@ -0,0 +1,15 @@
+# rc-minitest-openapi
+
+Generate an OpenAPI 3.0 document from your Rails minitest API tests.
+
+Tests declare each operation and its response schema; responses are validated
+against that schema as the suite runs; the `openapi:generate` rake task writes
+the document. A helper-method DSL and an rswag-style nested block DSL are both
+provided.
+
+See the [repository README](https://github.com/RailsComposer/minitest-openapi)
+for full documentation.
+
+## License
+
+MIT

data/lib/minitest/openapi/configuration.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module Minitest
+  module OpenAPI
+    # Per-suite settings. Configure in test_helper.rb:
+    #
+    #   Minitest::OpenAPI.configure do |c|
+    #     c.output_path = "openapi/v1/openapi.json"
+    #     c.base = "openapi/base.json"   # or a Hash
+    #   end
+    class Configuration
+      # Where openapi:generate writes the document (relative to Rails.root).
+      attr_accessor :output_path
+
+      # Validate each response body against its declared schema as tests run.
+      attr_accessor :validate_responses
+
+      DEFAULT_BASE = {
+        "openapi" => "3.0.3",
+        "info" => {"title" => "API", "version" => "1.0.0"},
+        "components" => {"schemas" => {}}
+      }.freeze
+
+      def initialize
+        @output_path = "openapi/openapi.json"
+        @validate_responses = true
+        @base = deep_dup(DEFAULT_BASE)
+      end
+
+      # The base document — everything not derived from tests (info, servers,
+      # security schemes, reusable component schemas). A Hash, or a path to a
+      # JSON/YAML file. Test-recorded operations are merged into `paths`.
+      attr_reader :base
+
+      def base=(value)
+        @base =
+          case value
+          when Hash then value
+          when String then load_base_file(value)
+          else raise ArgumentError, "base must be a Hash or a file path"
+          end
+      end
+
+      def base_document
+        deep_dup(@base)
+      end
+
+      private
+
+      def load_base_file(path)
+        resolved = Minitest::OpenAPI.resolve_path(path)
+        content = File.read(resolved)
+        path.end_with?(".json") ? JSON.parse(content) : YAML.safe_load(content)
+      end
+
+      def deep_dup(obj)
+        case obj
+        when Hash then obj.transform_values { |v| deep_dup(v) }
+        when Array then obj.map { |v| deep_dup(v) }
+        else obj
+        end
+      end
+    end
+  end
+end

data/lib/minitest/openapi/document.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Minitest
+  module OpenAPI
+    # The in-memory OpenAPI document. Tests record operations into it as they
+    # run; #to_h merges those operations into the base document's `paths`.
+    class Document
+      # Canonical ordering, so the emitted document is identical regardless
+      # of the order tests recorded into it (minitest randomizes test order).
+      VERB_ORDER = %w[get put post patch delete options head trace].freeze
+      OPERATION_KEYS = %w[
+        tags summary description operationId parameters requestBody responses
+      ].freeze
+
+      def initialize(base)
+        @base = base
+        @paths = {}
+      end
+
+      # The base document's reusable schemas, used to resolve $refs while
+      # validating responses.
+      def components
+        @base["components"] || {}
+      end
+
+      # Records one operation/response pair. Called by the recorder.
+      def record(verb:, path:, status:, schema: nil, summary: nil, operation_id: nil,
+        description: nil, tags: nil, parameters: nil, request_body: nil,
+        response_description: nil, content_type: "application/json")
+        operation = ((@paths[path] ||= {})[verb.to_s.downcase] ||= {})
+        operation["summary"] ||= summary if summary
+        operation["operationId"] ||= operation_id if operation_id
+        operation["description"] ||= description if description
+        operation["tags"] ||= tags if tags && !tags.empty?
+        operation["parameters"] ||= parameters if parameters && !parameters.empty?
+        operation["requestBody"] ||= request_body if request_body
+
+        responses = (operation["responses"] ||= {})
+        entry = (responses[status.to_s] ||= {})
+        entry["description"] ||= response_description || "#{status} response"
+        if schema
+          entry["content"] ||= {content_type => {"schema" => schema}}
+        end
+        operation
+      end
+
+      # The assembled document: the base with recorded operations merged into
+      # `paths`. Paths, verbs, operation keys, and response statuses are all
+      # canonically ordered, so the output is stable across test runs.
+      def to_h
+        doc = deep_dup(@base)
+        base_paths = doc["paths"] || {}
+        paths = {}
+        (base_paths.keys | @paths.keys).sort.each do |path|
+          merged = (base_paths[path] || {}).merge(@paths[path] || {})
+          paths[path] = canonical_path_item(merged)
+        end
+        doc["paths"] = paths
+        doc
+      end
+
+      def empty?
+        @paths.empty?
+      end
+
+      private
+
+      # Orders the verbs within a path item, and each operation's keys.
+      def canonical_path_item(verbs)
+        ordered = {}
+        (VERB_ORDER & verbs.keys).each { |verb| ordered[verb] = canonical_operation(verbs[verb]) }
+        (verbs.keys - VERB_ORDER).sort.each { |key| ordered[key] = verbs[key] }
+        ordered
+      end
+
+      # Orders an operation's keys and sorts its responses by status code.
+      def canonical_operation(operation)
+        ordered = {}
+        OPERATION_KEYS.each { |key| ordered[key] = operation[key] if operation.key?(key) }
+        (operation.keys - OPERATION_KEYS).sort.each { |key| ordered[key] = operation[key] }
+        if ordered["responses"].is_a?(Hash)
+          ordered["responses"] = ordered["responses"].sort_by { |status, _| status.to_i }.to_h
+        end
+        ordered
+      end
+
+      def deep_dup(obj)
+        case obj
+        when Hash then obj.transform_values { |v| deep_dup(v) }
+        when Array then obj.map { |v| deep_dup(v) }
+        else obj
+        end
+      end
+    end
+  end
+end

data/lib/minitest/openapi/dsl.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Minitest
+  module OpenAPI
+    # Helper-method DSL for classic class-based integration tests:
+    #
+    #   class MediaEntriesApiTest < ActionDispatch::IntegrationTest
+    #     include Minitest::OpenAPI::DSL
+    #
+    #     test "lists media entries" do
+    #       openapi_get "/api/v1/media_entries",
+    #         summary: "List media entries",
+    #         response: {status: 200, schema: {"$ref" => "#/components/schemas/MediaEntry"}}
+    #       assert_response :success
+    #     end
+    #   end
+    #
+    # Each openapi_<verb> performs the request, validates the response body
+    # against the declared schema, records the operation, and returns the
+    # response so further assertions can be made.
+    module DSL
+      %i[get post patch put delete].each do |verb|
+        define_method(:"openapi_#{verb}") do |request_path, response:, doc_path: nil, summary: nil, operation_id: nil, description: nil, tags: nil, parameters: nil, params: nil, headers: nil, body: nil, request_body: nil|
+          Recorder.run(
+            test: self, verb: verb, request_path: request_path, doc_path: doc_path,
+            response: response, summary: summary, operation_id: operation_id,
+            description: description, tags: tags, parameters: parameters,
+            params: params, headers: headers, body: body, request_body: request_body
+          )
+        end
+      end
+    end
+  end
+end

data/lib/minitest/openapi/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Minitest
+  module OpenAPI
+    class Railtie < Rails::Railtie
+      rake_tasks do
+        load File.expand_path("tasks/openapi.rake", __dir__)
+      end
+    end
+  end
+end

data/lib/minitest/openapi/recorder.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Minitest
+  module OpenAPI
+    # Shared engine behind both DSLs: performs the HTTP request through the
+    # integration test, validates the response body against the declared
+    # schema, and records the operation into the document.
+    module Recorder
+      module_function
+
+      # test         - the ActionDispatch::IntegrationTest instance
+      # verb          - :get/:post/:patch/:put/:delete
+      # request_path  - the URL to request
+      # doc_path      - templated path recorded in the document (default: request_path)
+      # response      - an Integer status, or { status:, schema:, description: }
+      # assert_status - when true, fails the test if the status differs
+      def run(test:, verb:, request_path:, response:, doc_path: nil, summary: nil,
+        operation_id: nil, description: nil, tags: nil, parameters: nil, params: nil,
+        headers: nil, body: nil, request_body: nil, assert_status: false)
+        spec = normalize_response(response)
+        doc_path ||= request_path
+
+        options = {}
+        payload = body.nil? ? params : body
+        options[:params] = payload unless payload.nil?
+        options[:headers] = headers if headers
+        options[:as] = :json unless body.nil?
+        test.public_send(verb, request_path, **options)
+
+        actual = test.response
+
+        Minitest::OpenAPI.document.record(
+          verb: verb, path: doc_path, status: spec[:status], schema: spec[:schema],
+          summary: summary, operation_id: operation_id, description: description,
+          tags: tags, parameters: parameters, request_body: request_body,
+          response_description: spec[:description]
+        )
+
+        if assert_status
+          test.assert_equal spec[:status], actual.status,
+            "expected #{verb.to_s.upcase} #{request_path} to respond #{spec[:status]}, " \
+            "got #{actual.status}"
+        end
+
+        if Minitest::OpenAPI.configuration.validate_responses &&
+            spec[:schema] && actual.status == spec[:status]
+          Validator.new(Minitest::OpenAPI.components).validate!(
+            spec[:schema], parse_body(actual),
+            context: "#{verb.to_s.upcase} #{doc_path} -> #{spec[:status]}"
+          )
+        end
+
+        actual
+      end
+
+      def normalize_response(response)
+        case response
+        when Integer
+          {status: response, schema: nil, description: nil}
+        when Hash
+          {status: Integer(response.fetch(:status)), schema: response[:schema],
+           description: response[:description]}
+        else
+          raise ArgumentError, "response: must be a status Integer or a Hash with :status"
+        end
+      end
+
+      def parse_body(actual)
+        JSON.parse(actual.body)
+      rescue JSON::ParserError
+        raise Validator::ResponseMismatch,
+          "response body was not valid JSON (HTTP #{actual.status})"
+      end
+    end
+  end
+end

data/lib/minitest/openapi/spec.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "minitest/spec"
+
+module Minitest
+  module OpenAPI
+    # Nested block DSL for minitest/spec users. Extend an integration test
+    # class with it; api_path / api_operation / api_response build nested
+    # describe blocks and run_api_test! defines the test:
+    #
+    #   class MediaEntriesApiTest < ActionDispatch::IntegrationTest
+    #     extend Minitest::OpenAPI::Spec
+    #
+    #     api_path "/api/v1/media_entries" do
+    #       api_operation :get, summary: "List media entries" do
+    #         api_response 200, schema: {"$ref" => "#/components/schemas/MediaEntry"} do
+    #           run_api_test!
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # Metadata accumulates down the nesting; run_api_test! merges the whole
+    # chain. Its optional block runs in the test instance and returns request
+    # overrides ({ path:, params:, headers:, body: }) — use it to build a
+    # concrete URL from records created in the test.
+    module Spec
+      def self.extended(base)
+        base.extend(Minitest::Spec::DSL) unless base.is_a?(Minitest::Spec::DSL)
+      end
+
+      # Metadata declared on this describe merged onto its parent's.
+      def openapi_metadata
+        inherited = superclass.respond_to?(:openapi_metadata) ? superclass.openapi_metadata : {}
+        inherited.merge(@openapi_metadata || {})
+      end
+
+      def api_path(path, &block)
+        describe("path #{path}") do
+          @openapi_metadata = {path: path}
+          class_eval(&block)
+        end
+      end
+
+      def api_operation(verb, **meta, &block)
+        describe(verb.to_s) do
+          @openapi_metadata = {verb: verb}.merge(meta)
+          class_eval(&block)
+        end
+      end
+
+      def api_response(status, **meta, &block)
+        describe("#{status} response") do
+          @openapi_metadata = {response_status: status}.merge(meta)
+          class_eval(&block)
+        end
+      end
+
+      def run_api_test!(description = nil, &request_block)
+        meta = openapi_metadata
+        verb = meta.fetch(:verb) { raise Error, "run_api_test! must be nested in api_operation" }
+        status = meta.fetch(:response_status) { raise Error, "run_api_test! must be nested in api_response" }
+        doc_path = meta.fetch(:path) { raise Error, "run_api_test! must be nested in api_path" }
+
+        it(description || "conforms to the #{status} response") do
+          overrides = request_block ? instance_exec(&request_block) : {}
+          overrides ||= {}
+          Recorder.run(
+            test: self,
+            verb: verb,
+            request_path: overrides[:path] || doc_path,
+            doc_path: doc_path,
+            response: {status: status, schema: meta[:schema], description: meta[:description]},
+            summary: meta[:summary],
+            operation_id: meta[:operation_id],
+            description: meta[:operation_description],
+            tags: meta[:tags],
+            parameters: meta[:parameters],
+            request_body: meta[:request_body],
+            params: overrides[:params],
+            headers: overrides[:headers],
+            body: overrides[:body],
+            assert_status: true
+          )
+        end
+      end
+    end
+  end
+end

data/lib/minitest/openapi/tasks/openapi.rake

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+namespace :openapi do
+  desc "Run the API tests and write the OpenAPI document. Pass test paths to " \
+       "scope the run, e.g. openapi:generate[test/integration/api]."
+  task :generate, [:paths] do |_task, args|
+    paths = [args[:paths], *args.extras].compact
+    paths = ["test/integration"] if paths.empty?
+    command = ["bin/rails", "test", *paths]
+    puts "openapi: #{command.join(" ")}"
+
+    # MINITEST_OPENAPI makes minitest-openapi write the document after the run.
+    # PARALLEL_WORKERS=1 keeps every operation in one process / one document.
+    env = {"MINITEST_OPENAPI" => "1", "PARALLEL_WORKERS" => "1"}
+    abort "openapi: test run failed; document not written" unless system(env, *command)
+  end
+end

data/lib/minitest/openapi/validator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "json_schemer"
+
+module Minitest
+  module OpenAPI
+    # Validates a response body against the schema a test declared for it.
+    # OpenAPI schemas are JSON Schema with a few divergences; `nullable: true`
+    # is normalized to a "null" type so a standard JSON Schema validator can
+    # be used. $refs of the form #/components/schemas/X resolve against the
+    # base document's components.
+    class Validator
+      class ResponseMismatch < StandardError; end
+
+      def initialize(components)
+        @components = components || {}
+      end
+
+      # Raises ResponseMismatch if `body` does not satisfy `schema`.
+      def validate!(schema, body, context:)
+        return if schema.nil?
+
+        root = {
+          "$schema" => "https://json-schema.org/draft/2020-12/schema",
+          "allOf" => [normalize(schema)],
+          "components" => normalize(@components)
+        }
+        errors = JSONSchemer.schema(root).validate(body).to_a
+        return if errors.empty?
+
+        raise ResponseMismatch, "#{context} response did not match its declared schema:\n" +
+          errors.first(8).map { |e| "  #{format_error(e)}" }.join("\n")
+      end
+
+      private
+
+      def format_error(error)
+        pointer = error["data_pointer"].to_s
+        location = pointer.empty? ? "(root)" : pointer
+        "#{location}: #{error["type"]}"
+      end
+
+      # OpenAPI `nullable: true` has no JSON Schema equivalent. Normalize it:
+      # add "null" to `type`, and — since an `enum` is exhaustive — add `nil`
+      # to any `enum` so a null value declared nullable is actually allowed.
+      def normalize(node)
+        case node
+        when Hash
+          normalized = node.each_with_object({}) { |(k, v), acc| acc[k] = normalize(v) }
+          if normalized.delete("nullable")
+            if normalized["type"].is_a?(String)
+              normalized["type"] = [normalized["type"], "null"]
+            end
+            if normalized["enum"].is_a?(Array) && !normalized["enum"].include?(nil)
+              normalized["enum"] += [nil]
+            end
+          end
+          normalized
+        when Array
+          node.map { |child| normalize(child) }
+        else
+          node
+        end
+      end
+    end
+  end
+end

data/lib/minitest/openapi/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Minitest
+  module OpenAPI
+    VERSION = "0.1.0"
+  end
+end

data/lib/minitest/openapi.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "pathname"
+require "fileutils"
+require "minitest"
+
+require_relative "openapi/version"
+require_relative "openapi/configuration"
+require_relative "openapi/document"
+require_relative "openapi/validator"
+require_relative "openapi/recorder"
+require_relative "openapi/dsl"
+require_relative "openapi/spec"
+
+require_relative "openapi/railtie" if defined?(Rails::Railtie)
+
+module Minitest
+  # Generates an OpenAPI 3.0 document from minitest API tests. Tests declare
+  # each operation and its response schema; the live response is validated
+  # against that schema as the suite runs; `openapi:generate` writes the doc.
+  module OpenAPI
+    class Error < StandardError; end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+      end
+
+      # The document being assembled this run.
+      def document
+        @document ||= Document.new(configuration.base_document)
+      end
+
+      # Component schemas available for $ref resolution during validation.
+      def components
+        document.components
+      end
+
+      # Drops the accumulated document (used between isolated test runs).
+      def reset!
+        @document = nil
+      end
+
+      # Writes the assembled document. Returns the absolute path written.
+      def generate!(path = nil)
+        target = resolve_path(path || configuration.output_path)
+        FileUtils.mkdir_p(File.dirname(target))
+        File.write(target, "#{JSON.pretty_generate(document.to_h)}\n")
+        target
+      end
+
+      # Resolves a path relative to Rails.root when available, else the cwd.
+      def resolve_path(path)
+        return path.to_s if Pathname.new(path).absolute?
+
+        root = defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+        File.join((root || Dir.pwd).to_s, path)
+      end
+    end
+  end
+end
+
+# When MINITEST_OPENAPI is set (the openapi:generate rake task sets it), write
+# the document once the suite finishes. Registered here, at require time,
+# rather than via a minitest plugin file: plugin auto-discovery is unreliable
+# under Rails' test runner and with git-sourced gems, whereas test_helper.rb
+# requires this file directly. Ordinary test runs leave MINITEST_OPENAPI unset
+# and are unaffected (responses are still validated; the file is just not
+# written).
+if ENV["MINITEST_OPENAPI"]
+  Minitest.after_run do
+    warn "minitest-openapi: wrote #{Minitest::OpenAPI.generate!}"
+  end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: rc-minitest-openapi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- RailsComposer
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: rc-minitest-openapi turns Rails minitest integration tests into the source
+  of truth for an OpenAPI 3.0 document. Tests declare each operation and its response
+  schema, the live response is validated against that schema as the suite runs, and
+  the openapi:generate rake task writes the document. An rswag-style block DSL and
+  plain helper methods are both supported.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/minitest/openapi.rb
+- lib/minitest/openapi/configuration.rb
+- lib/minitest/openapi/document.rb
+- lib/minitest/openapi/dsl.rb
+- lib/minitest/openapi/railtie.rb
+- lib/minitest/openapi/recorder.rb
+- lib/minitest/openapi/spec.rb
+- lib/minitest/openapi/tasks/openapi.rake
+- lib/minitest/openapi/validator.rb
+- lib/minitest/openapi/version.rb
+homepage: https://github.com/RailsComposer/minitest-openapi
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/RailsComposer/minitest-openapi
+  source_code_uri: https://github.com/RailsComposer/minitest-openapi
+  changelog_uri: https://github.com/RailsComposer/minitest-openapi/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Generate an OpenAPI document from your minitest API tests.
+test_files: []