miniswag 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b4952ed36467e585a435344a1742e8c78f0ff8a4fd1c0696690b78327872952
+  data.tar.gz: e01410bb9555e9de1c30c73a6731b817ff427593e8b2103611c2b74945b69b61
+SHA512:
+  metadata.gz: 0a1949b5278bd353be7bfa254218c02f0e780b99dd46d7769c3f033748a67fc6eadb884a0184c17fadf373b908fb89deba81ceeba960f86492c0f38672596065
+  data.tar.gz: bea825c1a547919423950a6b81d71b85af84baccc76516d5e9c3956de81a6848a6afee4dd735bbc85c4461549118a997c9d7bfb5af2f14c096ca251d922a15c1

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sika
+
+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/README.md

@@ -0,0 +1,255 @@
+# Miniswag
+
+OpenAPI (Swagger) documentation DSL for **Minitest**. A port of [rswag](https://github.com/rswag/rswag) that works with Minitest instead of RSpec.
+
+Write API integration tests that simultaneously validate your API responses and generate OpenAPI 3.x specification files — no RSpec required.
+
+## Gems
+
+| Gem | Description |
+|---|---|
+| `miniswag` | Core DSL and OpenAPI spec generator (replaces `rswag-specs`) |
+| `miniswag-api` | Rails engine that serves OpenAPI files as JSON/YAML endpoints (replaces `rswag-api`) |
+| `miniswag-ui` | Rails engine that serves Swagger UI powered by your OpenAPI specs (replaces `rswag-ui`) |
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+# Core — test DSL + spec generation
+gem "miniswag", group: :test
+
+# Optional — serve specs and Swagger UI in your app
+gem "miniswag-api"
+gem "miniswag-ui"
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate miniswag:install        # creates test/openapi_helper.rb
+rails generate miniswag:api:install    # creates config/initializers/miniswag_api.rb
+rails generate miniswag:ui:install     # creates config/initializers/miniswag_ui.rb
+```
+
+## Quick Start
+
+### 1. Configure your OpenAPI specs
+
+Edit `test/openapi_helper.rb`:
+
+```ruby
+require "miniswag"
+
+Miniswag.configure do |config|
+  config.openapi_root = Rails.root.join("docs/api").to_s
+
+  config.openapi_specs = {
+    "v1.yaml" => {
+      openapi: "3.0.1",
+      info: { title: "My API", version: "v1" },
+      servers: [{ url: "https://api.example.com" }]
+    }
+  }
+end
+```
+
+### 2. Write a test
+
+```ruby
+require "openapi_helper"
+
+class PetsTest < Miniswag::TestCase
+  path "/pets" do
+    get "Lists all pets" do
+      tags "Pets"
+      produces "application/json"
+
+      response 200, "successful" do
+        schema type: :array, items: { "$ref" => "#/components/schemas/Pet" }
+
+        run_test!
+      end
+    end
+
+    post "Creates a pet" do
+      tags "Pets"
+      consumes "application/json"
+      parameter name: :body, in: :body, schema: {
+        type: :object,
+        properties: {
+          name: { type: :string },
+          age: { type: :integer }
+        },
+        required: %w[name]
+      }
+
+      response 201, "pet created" do
+        params { { body: { name: "Fido", age: 3 } } }
+
+        run_test!
+      end
+
+      response 422, "invalid request" do
+        params { { body: { age: -1 } } }
+
+        run_test!
+      end
+    end
+  end
+end
+```
+
+### 3. Generate OpenAPI specs
+
+```bash
+rake miniswag:swaggerize
+```
+
+This runs your tests and writes the resulting OpenAPI files to `openapi_root`.
+
+## DSL Reference
+
+The DSL mirrors rswag closely. Key differences from rswag are noted below.
+
+### Structure
+
+```ruby
+class MyTest < Miniswag::TestCase
+  openapi_spec "admin.yaml"          # target a specific spec file
+
+  path "/resources/{id}" do
+    get "Fetch a resource" do
+      response 200, "success" do
+        run_test!
+      end
+    end
+  end
+end
+```
+
+### Parameters
+
+```ruby
+parameter name: :id, in: :path, type: :integer
+parameter name: :status, in: :query, type: :string
+parameter name: "X-Request-Id", in: :header, type: :string
+parameter name: :body, in: :body, schema: { type: :object, properties: { ... } }
+```
+
+Path parameters are automatically marked `required: true`.
+
+### Providing parameter values
+
+Instead of rswag's `let` blocks, use `params`:
+
+```ruby
+response 200, "success" do
+  params { { id: @resource.id, status: "active" } }
+  run_test!
+end
+```
+
+### Setup (replacing `let!` / `before`)
+
+```ruby
+response 200, "success" do
+  before { @resource = create_resource(name: "test") }
+  params { { id: @resource.id } }
+  run_test!
+end
+```
+
+### Custom assertions after the request
+
+```ruby
+run_test! do |response|
+  data = JSON.parse(response.body)
+  assert_equal "test", data["name"]
+end
+```
+
+### Operation attributes
+
+```ruby
+get "Fetch resource" do
+  tags "Resources"
+  operationId "getResource"
+  description "Returns a single resource by ID"
+  consumes "application/json"
+  produces "application/json"
+  security [{ bearer: [] }]
+  deprecated true
+end
+```
+
+### Response schema & headers
+
+```ruby
+response 200, "success" do
+  schema type: :object, properties: { id: { type: :integer } }
+  header "X-Rate-Limit", type: :integer, description: "Requests per hour"
+  run_test!
+end
+```
+
+### Request body examples
+
+```ruby
+post "Create resource" do
+  request_body_example value: { name: "example" }, summary: "Basic example"
+  # ...
+end
+```
+
+### Metadata (custom extensions)
+
+```ruby
+response 200, "success" do
+  metadata[:operation] ||= {}
+  metadata[:operation]["x-public-docs"] = true
+  run_test!
+end
+```
+
+## Migrating from rswag
+
+| rswag (RSpec) | miniswag (Minitest) |
+|---|---|
+| `RSpec.describe "...", type: :request do` | `class MyTest < Miniswag::TestCase` |
+| `let(:Authorization) { "Bearer ..." }` | `params { { Authorization: "Bearer ..." } }` |
+| `let!(:resource) { create(:resource) }` | `before { @resource = create(:resource) }` |
+| `let(:id) { resource.id }` | include in `params` block |
+| `let(:body) { { name: "x" } }` | include in `params` block |
+| `openapi_spec:` metadata on describe | `openapi_spec "name.yaml"` at class level |
+| `require "swagger_helper"` | `require "openapi_helper"` |
+
+## Configuration
+
+```ruby
+Miniswag.configure do |config|
+  # Required — where to write generated spec files
+  config.openapi_root = Rails.root.join("docs/api").to_s
+
+  # Required — spec definitions (supports multiple files)
+  config.openapi_specs = { "v1.yaml" => { openapi: "3.0.1", info: { ... } } }
+
+  # Optional — output format (:json or :yaml, default :yaml)
+  config.openapi_format = :yaml
+
+  # Optional — strict schema validation (rejects additional properties)
+  config.openapi_strict_schema_validation = false
+end
+```
+
+## Requirements
+
+- Ruby >= 3.1
+- Rails >= 7.0, < 9.0
+- Minitest ~> 5.0
+
+## License
+
+MIT. See [MIT-LICENSE](MIT-LICENSE).

data/lib/generators/miniswag/install/install_generator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Miniswag
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('templates', __dir__)
+
+    def copy_openapi_helper
+      template('openapi_helper.rb', 'test/openapi_helper.rb')
+    end
+  end
+end

data/lib/generators/miniswag/install/templates/openapi_helper.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+require 'miniswag'
+
+Miniswag.configure do |config|
+  # Root folder where OpenAPI spec files will be generated
+  config.openapi_root = Rails.root.join('openapi').to_s
+
+  # Output format: :json or :yaml
+  config.openapi_format = :json
+
+  # Define one or more OpenAPI specs
+  config.openapi_specs = {
+    'v1/openapi.json' => {
+      openapi: '3.0.1',
+      info: {
+        title: 'API V1',
+        version: 'v1'
+      },
+      paths: {},
+      servers: [
+        { url: 'http://localhost:3000' }
+      ]
+    }
+  }
+end

data/lib/miniswag/configuration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Miniswag
+  class Configuration
+    attr_accessor :openapi_root, :openapi_specs, :openapi_format,
+                  :openapi_all_properties_required, :openapi_no_additional_properties,
+                  :dry_run
+
+    def initialize
+      @openapi_root = nil
+      @openapi_specs = {}
+      @openapi_format = :json
+      @openapi_all_properties_required = false
+      @openapi_no_additional_properties = false
+      @dry_run = ENV.key?('MINISWAG_DRY_RUN') ? ENV['MINISWAG_DRY_RUN'] == '1' : true
+    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 validate!
+      raise ConfigurationError, 'No openapi_root provided. See openapi_helper.rb' if openapi_root.nil?
+      if openapi_specs.nil? || openapi_specs.empty?
+        raise ConfigurationError, 'No openapi_specs defined. See openapi_helper.rb'
+      end
+      return if %i[json yaml].include?(openapi_format)
+
+      raise ConfigurationError, "Unknown openapi_format '#{openapi_format}'"
+    end
+  end
+
+  class ConfigurationError < StandardError; end
+end

data/lib/miniswag/dsl.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/hash/deep_merge'
+
+module Miniswag
+  # Class-level DSL methods that mirror rswag's ExampleGroupHelpers.
+  #
+  # The DSL builds a tree of metadata on the test class. Each `path` block
+  # creates a path context, each verb block creates an operation context,
+  # and each `response` block creates a response context. `run_test!`
+  # generates a Minitest test method from the accumulated metadata.
+  #
+  # Metadata is stored in class instance variables and accumulated via
+  # a context stack so nested blocks see their parent metadata.
+  module DSL
+    def self.extended(base)
+      base.instance_variable_set(:@_miniswag_context_stack, [])
+      base.instance_variable_set(:@_miniswag_test_definitions, [])
+      base.instance_variable_set(:@_miniswag_openapi_spec_name, nil)
+    end
+
+    # Set which openapi spec file this test class targets (e.g. "admin.yaml")
+    def openapi_spec(name)
+      @_miniswag_openapi_spec_name = name
+    end
+
+    # ── Path block ──────────────────────────────────────────────────────
+
+    def path(template, &block)
+      ctx = { path_item: { template: template, parameters: [] }, scope: :path }
+      push_context(ctx, &block)
+    end
+
+    # ── HTTP verb blocks ────────────────────────────────────────────────
+
+    %i[get post patch put delete head options trace].each do |verb|
+      define_method(verb) do |summary, &block|
+        ctx = {
+          operation: {
+            verb: verb,
+            summary: summary,
+            parameters: []
+          },
+          scope: :operation
+        }
+        push_context(ctx, &block)
+      end
+    end
+
+    # ── Operation-level attributes ──────────────────────────────────────
+
+    %i[operationId deprecated security].each do |attr_name|
+      define_method(attr_name) do |value|
+        current_operation[attr_name] = value
+      end
+    end
+
+    def description(value)
+      current_operation[:description] = value
+    end
+
+    %i[tags consumes produces schemes].each do |attr_name|
+      define_method(attr_name) do |*value|
+        current_operation[attr_name] = value
+      end
+    end
+
+    # ── Parameters ──────────────────────────────────────────────────────
+
+    def parameter(attributes)
+      attributes[:required] = true if attributes[:in] && attributes[:in].to_sym == :path
+      scope = current_scope
+      if scope == :operation
+        current_operation[:parameters] ||= []
+        current_operation[:parameters] << attributes
+      else
+        current_path_item[:parameters] ||= []
+        current_path_item[:parameters] << attributes
+      end
+    end
+
+    def request_body_example(value:, summary: nil, name: nil)
+      return unless current_scope == :operation
+
+      current_operation[:request_examples] ||= []
+      example_entry = { value: value }
+      example_entry[:summary] = summary if summary
+      example_entry[:name] = name || current_operation[:request_examples].length
+      current_operation[:request_examples] << example_entry
+    end
+
+    # ── Response block ──────────────────────────────────────────────────
+
+    def response(code, description, &block)
+      ctx = {
+        response: { code: code, description: description },
+        scope: :response,
+        before_blocks: [],
+        params_block: nil,
+        after_test_block: nil
+      }
+      push_context(ctx, &block)
+    end
+
+    # ── Response-level attributes ───────────────────────────────────────
+
+    def schema(value)
+      current_response[:schema] = value
+    end
+
+    def header(name, attributes)
+      current_response[:headers] ||= {}
+      current_response[:headers][name] = attributes
+    end
+
+    def examples(examples_hash = nil)
+      return if examples_hash.nil?
+
+      examples_hash.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)
+      current_response[:content] = {} if current_response[:content].blank?
+      if current_response[:content][mime].blank?
+        current_response[:content][mime] = {}
+        current_response[:content][mime][:examples] = {}
+      end
+      example_object = { value: value, summary: summary, description: description }.compact
+      current_response[:content][mime][:examples].merge!(name.to_sym => example_object)
+    end
+
+    # ── Metadata access (for direct manipulation like metadata[:operation]["x-public-docs"]) ─
+
+    def metadata
+      @_miniswag_context_stack.last || {}
+    end
+
+    # ── Setup blocks within response context ────────────────────────────
+
+    # Register a block to run before the test request (within response context).
+    # Replaces RSpec's `let!` blocks for test data setup.
+    def before(&block)
+      ctx = @_miniswag_context_stack.last
+      ctx[:before_blocks] << block if ctx && ctx.key?(:before_blocks)
+    end
+
+    # Register a block that returns a hash of parameter values.
+    # Keys should match parameter names (including Authorization, path params, etc.)
+    def params(&block)
+      ctx = @_miniswag_context_stack.last
+      ctx[:params_block] = block if ctx
+    end
+
+    # ── Test generation ─────────────────────────────────────────────────
+
+    def run_test!(test_description = nil, &after_block)
+      # Snapshot all the accumulated metadata at this point
+      path_item = deep_dup(current_path_item)
+      operation = deep_dup(current_operation)
+      response_meta = deep_dup(current_response)
+      openapi_spec_name = @_miniswag_openapi_spec_name
+      before_blocks = (@_miniswag_context_stack.last[:before_blocks] || []).dup
+      params_block = @_miniswag_context_stack.last[:params_block]
+
+      test_description ||= "returns a #{response_meta[:code]} response"
+
+      # Build a unique test name from path + verb + response code + description
+      verb = operation[:verb]
+      path_template = path_item[:template]
+      test_name = "test_#{verb}_#{path_template}_#{response_meta[:code]}_#{test_description}"
+                  .gsub(/[^a-zA-Z0-9_]/, '_')
+                  .gsub(/_+/, '_')
+                  .downcase
+
+      # Build full metadata hash (mirrors rswag's metadata structure)
+      full_metadata = {
+        path_item: path_item,
+        operation: operation,
+        response: response_meta,
+        openapi_spec: openapi_spec_name
+      }
+
+      # Register for OpenAPI generation
+      @_miniswag_test_definitions ||= []
+      @_miniswag_test_definitions << full_metadata
+
+      # Register this class with the global registry for OpenAPI generation
+      Miniswag.register_test_class(self)
+
+      # Define the actual Minitest test method
+      user_block = after_block
+      captured_before_blocks = before_blocks
+      captured_params_block = params_block
+      captured_metadata = full_metadata
+
+      define_method(test_name) do
+        # Run before blocks in instance context
+        captured_before_blocks.each { |blk| instance_exec(&blk) }
+
+        # Collect params from the params block
+        test_params = captured_params_block ? instance_exec(&captured_params_block) : {}
+        test_params ||= {}
+
+        # Merge instance variable @_miniswag_params if set (from setup blocks)
+        if defined?(@_miniswag_params) && @_miniswag_params.is_a?(Hash)
+          test_params = @_miniswag_params.merge(test_params)
+        end
+
+        # Build and send request
+        factory = Miniswag::RequestFactory.new(captured_metadata, test_params)
+        request = factory.build_request
+
+        send(
+          request[:verb],
+          request[:path],
+          params: request[:payload],
+          headers: request[:headers]
+        )
+
+        # Validate response
+        validator = Miniswag::ResponseValidator.new
+        validator.validate!(captured_metadata, response)
+
+        # Run user's additional assertions
+        instance_exec(response, &user_block) if user_block
+      end
+    end
+
+    private
+
+    def push_context(ctx, &block)
+      @_miniswag_context_stack.push(ctx)
+      instance_exec(&block) if block
+      @_miniswag_context_stack.pop
+    end
+
+    def current_path_item
+      frame = @_miniswag_context_stack.find { |c| c[:scope] == :path }
+      frame ? frame[:path_item] : {}
+    end
+
+    def current_operation
+      frame = @_miniswag_context_stack.reverse.find { |c| c[:scope] == :operation }
+      frame ? frame[:operation] : {}
+    end
+
+    def current_response
+      frame = @_miniswag_context_stack.reverse.find { |c| c[:scope] == :response }
+      frame ? frame[:response] : {}
+    end
+
+    def current_scope
+      frame = @_miniswag_context_stack.last
+      frame ? frame[:scope] : nil
+    end
+
+    def deep_dup(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) { |(k, v), h| h[k] = deep_dup(v) }
+      when Array
+        obj.map { |v| deep_dup(v) }
+      else
+        obj.duplicable? ? obj.dup : obj
+      end
+    end
+  end
+end

data/lib/miniswag/extended_schema.rb

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

data/lib/miniswag/minitest_plugin.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'minitest'
+
+module Minitest
+  # Minitest plugin that triggers OpenAPI generation after the test suite.
+  # Activated by setting MINISWAG_GENERATE=1 or via the rake task.
+  def self.plugin_miniswag_init(options)
+    return unless ENV['MINISWAG_GENERATE'] == '1'
+
+    reporter << Miniswag::Reporter.new(options[:io], options)
+  end
+
+  def self.plugin_miniswag_options(opts, _options)
+    opts.on '--miniswag-generate', 'Generate OpenAPI specs after test run' do
+      ENV['MINISWAG_GENERATE'] = '1'
+    end
+  end
+end
+
+module Miniswag
+  class Reporter < Minitest::StatisticsReporter
+    def report
+      super
+      return if errors > 0 || failures > 0
+
+      puts 'Miniswag: Generating OpenAPI specs...'
+      require 'miniswag/openapi_generator'
+      generator = Miniswag::OpenapiGenerator.new
+      generator.generate!
+    end
+  end
+end