openapi_minitest 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7e0b37db854964620741255ac8d97c19570c3425977a9e6cb507de3a4212bfca
+  data.tar.gz: 7e03765531c01ebefb133856ab647e1626527f828481ed4d682cd8aa7896e49f
+SHA512:
+  metadata.gz: f666ddf8f5cb8e3986346d84b5920d7c07e7eb12a13c2f87324ebb7878d848a0bdd2f61dff0ca4611c713fad80cbd9e312e1a32019cc385058eaceaa2aa43d79
+  data.tar.gz: ac39441a39f4f8a8aa2828c7106f2c2ec34b101af98aca92d688a831ddbfd3d6404f75eff1234d3fb7832d66a8e8cda069c823c7d07d940621f1c020887ffd36

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.1

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0 (2026-02-06)
+
+
+### Features
+
+* add strict validation to catch undocumented fields ([767855b](https://github.com/k0va1/openapi_minitest/commit/767855b88d4d2c92fc633f366e6d71fddfd6232b))
+* initial implementation of openapi_minitest gem ([b41acd7](https://github.com/k0va1/openapi_minitest/commit/b41acd7c2ab2cfdb17c68f2ecc99771856c34c33))
+* output YAML format by default ([df930cf](https://github.com/k0va1/openapi_minitest/commit/df930cf925b73800dc628e3361019dc8bc453fc5))
+* update to OpenAPI 3.1.0 specification ([778e5f3](https://github.com/k0va1/openapi_minitest/commit/778e5f3166066c50878b7b0cc1e6b00746643cdd))
+
+
+### Bug Fixes
+
+* force initial release version to 0.1.0 ([a5b821d](https://github.com/k0va1/openapi_minitest/commit/a5b821decdea4a014cb12a2430ca33bb9ef4bc08))
+* reset ResultCollector between tests to prevent test pollution ([ecc5bc2](https://github.com/k0va1/openapi_minitest/commit/ecc5bc268a6e8833eebdc6566441c0032b93f2ec))
+* set manifest version to 0.0.0 for initial release as 0.1.0 ([7e340df](https://github.com/k0va1/openapi_minitest/commit/7e340dfdecc3bafdd1b3bf6147fc9e92e2e10f7e))
+* use security schemes instead of Authorization header parameter ([eb092ef](https://github.com/k0va1/openapi_minitest/commit/eb092efaa34ae92745c890d88dea18b8b55ca7f8))
+
+## Changelog

data/CLAUDE.md

@@ -0,0 +1,3 @@
+# Project Instructions
+
+- Use Conventional Commits format for all commit messages (e.g., `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`)

data/Makefile

@@ -0,0 +1,17 @@
+.PHONY: test lint-fix console install
+
+install:
+	bundle install
+
+console:
+	bin/console
+
+
+test:
+	bundle exec rake test
+
+
+
+lint-fix:
+	bundle exec standardrb --fix
+

data/README.md

@@ -0,0 +1,356 @@
+# OpenapiMinitest
+
+Generate OpenAPI 3.1 documentation from your Minitest integration tests. No DSL, no magic - just one helper method.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "openapi_minitest"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+### 1. Configure (optional)
+
+```ruby
+# config/initializers/openapi_minitest.rb (Rails)
+# or test/support/openapi.rb
+
+OpenapiMinitest.configure do |config|
+  config.title = "My API"
+  config.version = "1.0.0"
+  config.description = "API documentation"
+  config.output_path = "doc/openapi.yml"  # YAML by default
+  config.servers = ["https://api.example.com"]
+end
+```
+
+### 2. Define Schemas
+
+```ruby
+OpenapiMinitest.define_schema :User, {
+  type: :object,
+  properties: {
+    id: { type: :integer },
+    email: { type: :string, format: :email },
+    name: { type: :string }
+  },
+  required: %w[id email]
+}
+
+OpenapiMinitest.define_schema :UserList, {
+  type: :object,
+  properties: {
+    data: { type: :array, items: { "$ref" => "#/components/schemas/User" } },
+    meta: {
+      type: :object,
+      properties: {
+        total: { type: :integer },
+        page: { type: :integer }
+      }
+    }
+  }
+}
+
+OpenapiMinitest.define_schema :Error, {
+  type: :object,
+  properties: {
+    error: { type: :string },
+    code: { type: :integer }
+  }
+}
+```
+
+### 3. Write Tests
+
+Write normal Minitest tests. Call `document_response` after each request you want documented:
+
+```ruby
+class UsersApiTest < ActionDispatch::IntegrationTest
+  def test_returns_users
+    create(:user, name: "John")
+    create(:user, name: "Jane")
+
+    get "/api/users", headers: auth_headers
+
+    assert_response 200
+    document_response schema: :UserList, description: "Returns all users"
+
+    body = JSON.parse(response.body)
+    assert_equal 2, body["data"].size
+  end
+
+  def test_filters_users_by_name
+    create(:user, name: "John")
+    create(:user, name: "Jane")
+
+    get "/api/users", params: { q: "John" }, headers: auth_headers
+
+    assert_response 200
+    document_response schema: :UserList, description: "Filters users by name"
+
+    body = JSON.parse(response.body)
+    assert_equal 1, body["data"].size
+  end
+
+  def test_returns_single_user
+    user = create(:user, name: "John")
+
+    get "/api/users/#{user.id}", headers: auth_headers
+
+    assert_response 200
+    document_response schema: :User, description: "User found", tags: ["Users"]
+  end
+
+  def test_user_not_found
+    get "/api/users/999999", headers: auth_headers
+
+    assert_response 404
+    document_response schema: :Error, description: "User not found"
+  end
+
+  def test_creates_user
+    post "/api/users",
+      params: { user: { name: "New User", email: "new@example.com" } },
+      headers: auth_headers,
+      as: :json
+
+    assert_response 201
+    document_response schema: :User, description: "User created", tags: ["Users"]
+  end
+
+  def test_create_user_validation_error
+    post "/api/users",
+      params: { user: { name: "" } },
+      headers: auth_headers,
+      as: :json
+
+    assert_response 422
+    document_response schema: :Error, description: "Validation failed"
+  end
+
+  private
+
+  def auth_headers
+    { "Authorization" => "Bearer #{generate_token}" }
+  end
+end
+```
+
+### 4. Generate Documentation
+
+```bash
+# Run tests with documentation generation
+OPENAPI_GENERATE=true rails test test/integration/
+
+# Or use the rake task
+rails openapi:generate
+```
+
+## API Reference
+
+### Configuration Options
+
+```ruby
+OpenapiMinitest.configure do |config|
+  config.title = "My API"              # API title
+  config.version = "1.0.0"             # API version
+  config.description = "Description"   # API description
+  config.output_path = "doc/openapi.yml"  # Output file path (YAML by default)
+  config.servers = [                   # Server URLs
+    "https://api.example.com",
+    { url: "https://staging.example.com", description: "Staging" }
+  ]
+  config.security_schemes = {          # Security schemes
+    bearer: {
+      type: :http,
+      scheme: :bearer
+    }
+  }
+  config.validate_schema = true        # Validate responses against schemas
+  config.strict_validation = false     # Fail if response contains undocumented fields
+end
+```
+
+### document_response
+
+Call after making a request to record it for documentation:
+
+```ruby
+document_response(
+  schema: :SchemaName,          # Schema reference (Symbol) or inline schema (Hash)
+  summary: "Operation summary", # Defaults to test name
+  description: "Response desc", # Description of this response
+  tags: ["Tag1", "Tag2"],       # Tags for grouping
+  operation_id: "getUsers",     # Unique operation ID
+  deprecated: false,            # Mark endpoint as deprecated
+  strict: nil                   # Override strict validation (true/false/nil for global config)
+)
+```
+
+### Schema Definition
+
+```ruby
+# Reference to another schema
+OpenapiMinitest.define_schema :UserList, {
+  type: :object,
+  properties: {
+    data: { type: :array, items: { "$ref" => "#/components/schemas/User" } }
+  }
+}
+
+# Inline schema in tests
+document_response schema: {
+  type: :object,
+  properties: {
+    status: { type: :string }
+  }
+}
+
+# Nullable fields (OpenAPI 3.1 syntax - use type array instead of nullable: true)
+OpenapiMinitest.define_schema :Article, {
+  type: :object,
+  properties: {
+    id: { type: :integer },
+    title: { type: :string },
+    subtitle: { type: [:string, :null] },  # nullable string
+    published_at: { type: [:string, :null], format: :datetime }
+  }
+}
+```
+
+## Features
+
+- **No DSL** - Just one helper method, write normal Minitest tests
+- **Schema validation** - Optionally validate responses against schemas during tests
+- **Strict validation** - Fail tests when responses contain undocumented fields
+- **Auto-detection** - Automatically extracts path parameters, query params
+- **Security handling** - Authorization headers automatically use configured security schemes
+- **Multiple examples** - Each test becomes an example in the docs
+- **Request bodies** - Captures POST/PUT/PATCH request bodies as examples
+
+## Strict Validation
+
+Enable strict validation to catch undocumented fields in API responses. This helps ensure your documentation stays in sync with your implementation.
+
+When strict mode is enabled, the test will fail if the response contains any fields not defined in the schema:
+
+```
+Response does not match schema:
+The property '#/' contains additional properties ["unexpected_field"] outside of the schema when none are allowed
+```
+
+### Global Configuration
+
+```ruby
+OpenapiMinitest.configure do |config|
+  config.strict_validation = true  # All schemas strictly validated
+end
+```
+
+### Per-Call Override
+
+```ruby
+# Force strict validation for this endpoint
+document_response schema: :User, strict: true
+
+# Disable strict validation for this endpoint (e.g., third-party responses)
+document_response schema: :ExternalData, strict: false
+
+# Use global config setting (default behavior)
+document_response schema: :User
+```
+
+Strict validation works by automatically injecting `additionalProperties: false` into all object schemas during validation. This includes nested objects and objects within arrays. If a schema already defines `additionalProperties`, that value is preserved.
+
+## How It Works
+
+1. You write normal integration tests
+2. Call `document_response` after requests you want documented
+3. The gem captures:
+   - Request method, path, parameters, headers
+   - Response status, body
+   - Schema reference or definition
+4. After tests run, generates OpenAPI 3.1 YAML
+
+## Path Parameter Detection
+
+The gem automatically detects numeric IDs in paths and converts them:
+
+```
+/api/users/123           -> /api/users/{user_id}
+/api/users/123/posts/456 -> /api/users/{user_id}/posts/{post_id}
+```
+
+## Security / Authentication
+
+When you configure `security_schemes` and your tests include an `Authorization` header, the gem automatically adds the `security` property to those operations:
+
+```ruby
+OpenapiMinitest.configure do |config|
+  config.security_schemes = {
+    bearer: {
+      type: :http,
+      scheme: :bearer
+    }
+  }
+end
+```
+
+Operations with Authorization headers will be generated with:
+
+```yaml
+security:
+  - bearer: []
+```
+
+## Validator Compatibility
+
+This gem generates OpenAPI 3.1.0 which supports type arrays for nullable fields:
+
+```yaml
+type:
+  - string
+  - 'null'
+```
+
+Some validators may not fully support OpenAPI 3.1.0 yet. If you encounter validation errors about type arrays, ensure your validator supports OpenAPI 3.1.0.
+
+## Non-Rails Usage
+
+Include the DSL module manually:
+
+```ruby
+class MyApiTest < Minitest::Test
+  include OpenapiMinitest::DSL
+
+  # ... your tests
+end
+
+# Generate documentation after tests
+Minitest.after_run do
+  if ENV["OPENAPI_GENERATE"]
+    OpenapiMinitest::OpenAPI::Generator.new.write
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/k0va1/openapi_minitest.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]

data/lib/openapi_minitest/configuration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module OpenapiMinitest
+  class Configuration
+    attr_accessor :title,
+      :version,
+      :description,
+      :output_path,
+      :servers,
+      :security_schemes,
+      :tags,
+      :validate_schema,
+      :strict_validation
+
+    def initialize
+      @title = "API Documentation"
+      @version = "1.0.0"
+      @description = nil
+      @output_path = "doc/openapi.yml"
+      @servers = []
+      @security_schemes = {}
+      @tags = []
+      @validate_schema = true
+      @strict_validation = false
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset!
+      @configuration = Configuration.new
+      @schemas = {}
+    end
+
+    # Schema registry
+    def schemas
+      @schemas ||= {}
+    end
+
+    def define_schema(name, definition)
+      schemas[name.to_sym] = definition
+    end
+
+    def schema(name)
+      schemas[name.to_sym]
+    end
+  end
+end

data/lib/openapi_minitest/dsl.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "json"
+require "json-schema"
+
+module OpenapiMinitest
+  module DSL
+    # Records the current request/response for OpenAPI documentation.
+    #
+    # Call this after making a request and asserting the response status.
+    # It captures all the details needed for OpenAPI generation.
+    #
+    # @param schema [Symbol, Hash, nil] Schema name (references defined schema) or inline schema hash
+    # @param summary [String, nil] Short summary of the operation (defaults to test name)
+    # @param description [String, nil] Description of this specific response
+    # @param tags [Array<String>] Tags for grouping endpoints
+    # @param operation_id [String, nil] Unique operation identifier
+    # @param deprecated [Boolean] Whether this endpoint is deprecated
+    # @param strict [Boolean, nil] Strict validation mode - fails if response contains undocumented fields.
+    #   When nil (default), uses the global config.strict_validation setting.
+    #
+    # @example Basic usage
+    #   def test_returns_users
+    #     get "/api/users"
+    #     assert_response 200
+    #     document_response schema: :UserList, description: "Returns all users"
+    #   end
+    #
+    # @example With tags and summary
+    #   def test_creates_user
+    #     post "/api/users", params: { name: "John" }
+    #     assert_response 201
+    #     document_response schema: :User, summary: "Create user", tags: ["Users"]
+    #   end
+    #
+    # @example Inline schema
+    #   def test_health_check
+    #     get "/health"
+    #     assert_response 200
+    #     document_response schema: { type: :object, properties: { status: { type: :string } } }
+    #   end
+    #
+    # @example Without schema (just documents the endpoint)
+    #   def test_deletes_user
+    #     delete "/api/users/1"
+    #     assert_response 204
+    #     document_response description: "User deleted"
+    #   end
+    #
+    # @example Strict validation (fails if response has undocumented fields)
+    #   def test_returns_user_strict
+    #     get "/api/users/1"
+    #     assert_response 200
+    #     document_response schema: :User, strict: true
+    #   end
+    #
+    def document_response(schema: nil, summary: nil, description: nil, tags: [], operation_id: nil, deprecated: false, strict: nil)
+      # Validate schema if provided and validation is enabled
+      if schema && OpenapiMinitest.configuration.validate_schema && response.body.present?
+        use_strict = strict.nil? ? OpenapiMinitest.configuration.strict_validation : strict
+        validate_response_schema!(schema, strict: use_strict)
+      end
+
+      # Record for OpenAPI generation
+      ResultCollector.instance.record(
+        request: request,
+        response: response,
+        schema: normalize_schema(schema),
+        summary: summary || generate_summary,
+        description: description,
+        tags: Array(tags),
+        operation_id: operation_id,
+        deprecated: deprecated,
+        test_name: name
+      )
+    end
+
+    private
+
+    def validate_response_schema!(schema, strict: false)
+      resolved = resolve_schema(schema)
+      resolved = apply_strict_validation(resolved) if strict
+      body = JSON.parse(response.body)
+
+      errors = JSON::Validator.fully_validate(
+        stringify_keys(resolved),
+        body,
+        strict: false,
+        clear_cache: true
+      )
+
+      return if errors.empty?
+
+      flunk "Response does not match schema:\n#{errors.join("\n")}\n\nBody: #{response.body}"
+    rescue JSON::ParserError => e
+      flunk "Response is not valid JSON: #{e.message}"
+    end
+
+    def apply_strict_validation(schema)
+      case schema
+      when Hash
+        result = schema.transform_values { |v| apply_strict_validation(v) }
+        # Add additionalProperties: false to object types
+        if object_type?(result)
+          result[:additionalProperties] = false unless result.key?(:additionalProperties) || result.key?("additionalProperties")
+        end
+        result
+      when Array
+        schema.map { |item| apply_strict_validation(item) }
+      else
+        schema
+      end
+    end
+
+    def object_type?(schema)
+      type = schema[:type] || schema["type"]
+      return false unless type
+
+      case type
+      when :object, "object"
+        true
+      when Array
+        type.any? { |t| t == :object || t == "object" }
+      else
+        false
+      end
+    end
+
+    def resolve_schema(schema)
+      case schema
+      when Symbol
+        referenced = OpenapiMinitest.schema(schema)
+        raise ArgumentError, "Unknown schema: #{schema}" unless referenced
+        deep_resolve_refs(deep_dup(referenced))
+      when Hash
+        deep_resolve_refs(deep_dup(schema))
+      else
+        schema
+      end
+    end
+
+    def deep_resolve_refs(obj)
+      case obj
+      when Hash
+        if obj[:$ref] || obj["$ref"]
+          ref = obj[:$ref] || obj["$ref"]
+          if ref.to_s.start_with?("#/components/schemas/")
+            schema_name = ref.to_s.split("/").last.to_sym
+            referenced = OpenapiMinitest.schema(schema_name)
+            if referenced
+              return deep_resolve_refs(deep_dup(referenced))
+            end
+          end
+        end
+        obj.transform_values { |v| deep_resolve_refs(v) }
+      when Array
+        obj.map { |item| deep_resolve_refs(item) }
+      else
+        obj
+      end
+    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 { |item| deep_dup(item) }
+      else
+        obj
+      end
+    end
+
+    def stringify_keys(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(key, value), result|
+          result[key.to_s] = stringify_keys(value)
+        end
+      when Array
+        obj.map { |item| stringify_keys(item) }
+      else
+        obj
+      end
+    end
+
+    def normalize_schema(schema)
+      case schema
+      when Symbol
+        {"$ref" => "#/components/schemas/#{schema}"}
+      when Hash
+        stringify_keys(schema)
+      end
+    end
+
+    def generate_summary
+      # Convert test_creates_user -> "Creates user"
+      name.to_s
+        .sub(/^test_/, "")
+        .tr("_", " ")
+        .capitalize
+    end
+  end
+end

data/lib/openapi_minitest/openapi/generator.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module OpenapiMinitest
+  module OpenAPI
+    class Generator
+      def initialize
+        @config = OpenapiMinitest.configuration
+        @collector = ResultCollector.instance
+      end
+
+      def generate
+        {
+          "openapi" => "3.1.0",
+          "info" => build_info,
+          "servers" => build_servers,
+          "paths" => build_paths,
+          "components" => build_components
+        }.compact
+      end
+
+      def write
+        path = @config.output_path
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, generate.to_yaml)
+        path
+      end
+
+      private
+
+      def build_info
+        info = {
+          "title" => @config.title,
+          "version" => @config.version
+        }
+        info["description"] = @config.description if @config.description
+        info
+      end
+
+      def build_servers
+        return nil if @config.servers.empty?
+
+        @config.servers.map do |server|
+          case server
+          when String
+            {"url" => server}
+          when Hash
+            stringify_keys(server)
+          end
+        end
+      end
+
+      def build_paths
+        paths = {}
+
+        @collector.operations.each do |key, operation|
+          path = operation[:path]
+          method = operation[:method]
+
+          paths[path] ||= {}
+          paths[path][method] = build_operation(key, operation)
+        end
+
+        paths
+      end
+
+      def build_operation(key, operation)
+        op = {}
+
+        op["summary"] = operation[:summary] if operation[:summary]
+        op["tags"] = operation[:tags] if operation[:tags]&.any?
+        op["operationId"] = operation[:operation_id] if operation[:operation_id]
+        op["deprecated"] = true if operation[:deprecated]
+
+        # Security (if operation requires auth and security schemes are configured)
+        if operation[:requires_auth] && @config.security_schemes.any?
+          op["security"] = @config.security_schemes.keys.map { |scheme| {scheme.to_s => []} }
+        end
+
+        # Parameters
+        if operation[:parameters]&.any?
+          op["parameters"] = operation[:parameters].map { |p| stringify_keys(p) }
+        end
+
+        # Request body (for POST/PUT/PATCH)
+        request_body = build_request_body(key, operation[:method])
+        op["requestBody"] = request_body if request_body
+
+        # Responses
+        op["responses"] = build_responses(key)
+
+        op
+      end
+
+      def build_request_body(key, method)
+        return nil unless %w[post put patch].include?(method)
+
+        responses = @collector.responses[key]
+        return nil unless responses
+
+        # Find a request example from any response
+        example = nil
+        responses.each_value do |response_list|
+          response_list.each do |resp|
+            if resp[:request_example]
+              example = resp[:request_example]
+              break
+            end
+          end
+          break if example
+        end
+
+        return nil unless example
+
+        {
+          "required" => true,
+          "content" => {
+            "application/json" => {
+              "schema" => {"type" => "object"},
+              "example" => example
+            }
+          }
+        }
+      end
+
+      def build_responses(key)
+        responses_data = @collector.responses[key] || {}
+        responses = {}
+
+        responses_data.each do |status, response_list|
+          primary = response_list.first
+
+          response = {
+            "description" => primary[:description]
+          }
+
+          # Add content with schema and examples
+          if primary[:schema] || primary[:example]
+            content = {}
+
+            content["schema"] = primary[:schema] if primary[:schema]
+
+            # Build examples from all responses with this status
+            if response_list.any? { |r| r[:example] }
+              examples = {}
+              response_list.each do |resp|
+                next unless resp[:example]
+                example_name = resp[:test_name] || "example"
+                examples[example_name] = {
+                  "value" => resp[:example]
+                }
+              end
+              content["examples"] = examples if examples.any?
+            end
+
+            response["content"] = {
+              "application/json" => content
+            }
+          end
+
+          responses[status] = response
+        end
+
+        # Ensure at least one response
+        responses["200"] = {"description" => "Successful response"} if responses.empty?
+
+        responses
+      end
+
+      def build_components
+        components = {}
+
+        # Add registered schemas
+        if OpenapiMinitest.schemas.any?
+          components["schemas"] = {}
+          OpenapiMinitest.schemas.each do |name, schema|
+            components["schemas"][name.to_s] = stringify_keys(schema)
+          end
+        end
+
+        # Add security schemes
+        if @config.security_schemes.any?
+          components["securitySchemes"] = stringify_keys(@config.security_schemes)
+        end
+
+        components.empty? ? nil : components
+      end
+
+      def stringify_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(key, value), result|
+            result[key.to_s] = stringify_keys(value)
+          end
+        when Array
+          obj.map { |item| stringify_keys(item) }
+        when Symbol
+          obj.to_s
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/openapi_minitest/railtie.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module OpenapiMinitest
+  class Railtie < Rails::Railtie
+    railtie_name :openapi_minitest
+
+    rake_tasks do
+      namespace :openapi do
+        desc "Generate OpenAPI documentation from tests"
+        task generate: :environment do
+          ENV["OPENAPI_GENERATE"] = "true"
+
+          require "rails/test_unit/runner"
+          Rails::TestUnit::Runner.run(ARGV)
+        end
+      end
+    end
+
+    initializer "openapi_minitest.configure" do
+      ActiveSupport.on_load(:action_dispatch_integration_test) do
+        include OpenapiMinitest::DSL
+      end
+    end
+
+    config.after_initialize do
+      if Rails.env.test?
+        Minitest.after_run do
+          if ENV["OPENAPI_GENERATE"] == "true" && !OpenapiMinitest::ResultCollector.instance.empty?
+            path = OpenapiMinitest::OpenAPI::Generator.new.write
+            puts "\nOpenAPI documentation generated: #{path}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openapi_minitest/result_collector.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "json"
+
+module OpenapiMinitest
+  class ResultCollector
+    include Singleton
+
+    def initialize
+      reset!
+    end
+
+    def reset!
+      @operations = {}  # "METHOD /path" => operation data
+      @responses = {}   # "METHOD /path" => { status => [response_data] }
+    end
+
+    def record(request:, response:, schema:, summary:, description:, tags:, operation_id:, deprecated:, test_name:)
+      method = request.request_method.downcase
+      path = normalize_path(request.path)
+      key = "#{method} #{path}"
+
+      # Store operation metadata (first one wins for summary, tags merge)
+      @operations[key] ||= {
+        method: method,
+        path: path,
+        summary: summary,
+        tags: [],
+        operation_id: operation_id,
+        deprecated: deprecated,
+        parameters: extract_parameters(request, path),
+        requires_auth: has_authorization_header?(request)
+      }
+
+      # Merge tags from all tests
+      @operations[key][:tags] = (@operations[key][:tags] + tags).uniq
+
+      # Store response data grouped by status
+      status = response.status.to_s
+      @responses[key] ||= {}
+      @responses[key][status] ||= []
+
+      @responses[key][status] << {
+        description: description || default_description(response.status),
+        schema: schema,
+        example: parse_body(response.body),
+        test_name: test_name,
+        request_example: extract_request_example(request)
+      }
+    end
+
+    attr_reader :operations
+
+    attr_reader :responses
+
+    def empty?
+      @operations.empty?
+    end
+
+    private
+
+    def normalize_path(path)
+      # Convert /api/users/123 to /api/users/{id}
+      # Convert /api/users/123/posts/456 to /api/users/{id}/posts/{post_id}
+      segments = path.split("/")
+      normalized = []
+      param_counts = Hash.new(0)
+
+      segments.each_with_index do |segment, index|
+        if segment.match?(/^\d+$/)
+          # This is an ID - figure out what to call it
+          prev_segment = segments[index - 1]
+          if prev_segment
+            # Singularize: users -> user_id, posts -> post_id
+            param_name = singularize(prev_segment) + "_id"
+            # Handle multiple params of same type
+            if param_counts[param_name] > 0
+              param_name = "#{param_name}_#{param_counts[param_name] + 1}"
+            end
+            param_counts[param_name] += 1
+            # First occurrence of a resource ID is just {id} for cleaner paths
+            param_name = "id" if param_counts[param_name] == 1 && normalized.size == segments.size - 2
+            normalized << "{#{param_name}}"
+          else
+            normalized << "{id}"
+          end
+        else
+          normalized << segment
+        end
+      end
+
+      normalized.join("/")
+    end
+
+    def singularize(word)
+      # Basic singularization - in Rails app, would use ActiveSupport
+      if word.end_with?("ies")
+        word[0..-4] + "y"
+      elsif word.end_with?("ses", "xes", "zes", "ches", "shes")
+        word[0..-3]
+      elsif word.end_with?("s") && !word.end_with?("ss")
+        word[0..-2]
+      else
+        word
+      end
+    end
+
+    def extract_parameters(request, normalized_path)
+      params = []
+
+      # Path parameters
+      normalized_path.scan(/\{(\w+)\}/).flatten.each do |param_name|
+        params << {
+          name: param_name,
+          in: "path",
+          required: true,
+          schema: {type: "string"}
+        }
+      end
+
+      # Query parameters
+      if request.query_parameters.any?
+        request.query_parameters.each do |name, value|
+          params << {
+            name: name.to_s,
+            in: "query",
+            required: false,
+            schema: infer_schema_type(value)
+          }
+        end
+      end
+
+      # Note: Authorization header is handled via security schemes, not parameters
+
+      params
+    end
+
+    def has_authorization_header?(request)
+      !!(request.headers["Authorization"] || request.headers["HTTP_AUTHORIZATION"])
+    end
+
+    def infer_schema_type(value)
+      case value
+      when Integer then {type: "integer"}
+      when Float then {type: "number"}
+      when TrueClass, FalseClass then {type: "boolean"}
+      when Array then {type: "array", items: {type: "string"}}
+      else {type: "string"}
+      end
+    end
+
+    def extract_request_example(request)
+      return nil if request.request_method == "GET"
+
+      body = request.body.read
+      request.body.rewind
+      return nil if body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def parse_body(body)
+      return nil if body.nil? || body.empty?
+      JSON.parse(body)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def default_description(status)
+      {
+        200 => "Successful response",
+        201 => "Created",
+        204 => "No content",
+        400 => "Bad request",
+        401 => "Unauthorized",
+        403 => "Forbidden",
+        404 => "Not found",
+        422 => "Unprocessable entity",
+        500 => "Internal server error"
+      }[status] || "Response"
+    end
+  end
+end

data/lib/openapi_minitest/version.rb

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

data/lib/openapi_minitest.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "openapi_minitest/version"
+require_relative "openapi_minitest/configuration"
+require_relative "openapi_minitest/result_collector"
+require_relative "openapi_minitest/dsl"
+require_relative "openapi_minitest/openapi/generator"
+
+require_relative "openapi_minitest/railtie" if defined?(Rails::Railtie)
+
+module OpenapiMinitest
+  class Error < StandardError; end
+  class SchemaValidationError < Error; end
+end

data/release-please-config.json

@@ -0,0 +1,17 @@
+{
+  "packages": {
+    ".": {
+      "package-name": "openapi_minitest",
+      "include-component-in-tag": false,
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "ruby",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": true,
+      "draft": false,
+      "prerelease": false,
+      "version-file": "lib/openapi_minitest/version.rb",
+      "release-as": "0.1.0"
+    }
+  },
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"
+}

data/sig/openapi_minitest.rbs

@@ -0,0 +1,4 @@
+module OpenapiMinitest
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: openapi_minitest
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alex Koval
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  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: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Ruby gem that generates OpenAPI 3.0 documentation from Minitest integration
+  tests in Rails applications. Uses serializers as the single source of truth for
+  response schemas.
+email:
+- al3xander.koval@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".release-please-manifest.json"
+- ".standard.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- Makefile
+- README.md
+- Rakefile
+- lib/openapi_minitest.rb
+- lib/openapi_minitest/configuration.rb
+- lib/openapi_minitest/dsl.rb
+- lib/openapi_minitest/openapi/generator.rb
+- lib/openapi_minitest/railtie.rb
+- lib/openapi_minitest/result_collector.rb
+- lib/openapi_minitest/version.rb
+- release-please-config.json
+- sig/openapi_minitest.rbs
+homepage: https://github.com/k0va1/openapi_minitest
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/k0va1/openapi_minitest
+  source_code_uri: https://github.com/k0va1/openapi_minitest
+  changelog_uri: https://github.com/k0va1/openapi_minitest/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+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 OpenAPI documentation from Minitest integration tests
+test_files: []