openapi_minitest 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e0b37db854964620741255ac8d97c19570c3425977a9e6cb507de3a4212bfca
-  data.tar.gz: 7e03765531c01ebefb133856ab647e1626527f828481ed4d682cd8aa7896e49f
+  metadata.gz: e720190cb7ad695482a4e3200826cd437acc19b6cb6d00423b628d5e5efb7416
+  data.tar.gz: ee6598e687c92d030492cef298cb78fbbec2c0b76ec529f64d2f47172847f631
 SHA512:
-  metadata.gz: f666ddf8f5cb8e3986346d84b5920d7c07e7eb12a13c2f87324ebb7878d848a0bdd2f61dff0ca4611c713fad80cbd9e312e1a32019cc385058eaceaa2aa43d79
-  data.tar.gz: ac39441a39f4f8a8aa2828c7106f2c2ec34b101af98aca92d688a831ddbfd3d6404f75eff1234d3fb7832d66a8e8cda069c823c7d07d940621f1c020887ffd36
+  metadata.gz: 251b5d8354681ffa184b5ccedf8df342034083c9b0e1a3f1b28216f6d9b593214e60f040f12be12737fc9fe5897f34eee5cd030de985cb341d81045fe7c2c1da
+  data.tar.gz: 3fbcf78209751bab3a1f95f2fb86c5ce0bc7500b22b0f87938fb59ac9ffeedbd7112380fe7d0829bf75744093dd6c24e1f7e31689f78c41898f2a5b6e4a39de2

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.1.1](https://github.com/k0va1/openapi_minitest/compare/v0.1.0...v0.1.1) (2026-02-10)
+
+
+### Features
+
+* add configurable path sorting with sort_paths option ([432d5ea](https://github.com/k0va1/openapi_minitest/commit/432d5ea33586adc2a09dd0d6c9ff086767b7fbc5))
+* add Rails generator for API docs controller with Scalar UI ([77b5627](https://github.com/k0va1/openapi_minitest/commit/77b562717bddf97ecc1c67b27855bf1e4673d1c5))
+* add thread safety to ResultCollector using MonitorMixin ([18dd97d](https://github.com/k0va1/openapi_minitest/commit/18dd97dcd2b1925b2caee98eb6d45c3194e5da74))
+
 ## 0.1.0 (2026-02-06)
 
 
@@ -17,5 +26,3 @@
 * 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

@@ -1,3 +1,37 @@
-# Project Instructions
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+openapi_minitest is a Ruby gem that generates OpenAPI 3.1.0 documentation from Minitest integration tests. Users call a single `document_response` helper method in their tests to capture API endpoints into an OpenAPI YAML file.
+
+## Commands
+
+- **Run all tests + lint:** `bundle exec rake` (default task runs both `test` and `standard`)
+- **Run tests only:** `bundle exec rake test`
+- **Run a single test:** `bundle exec ruby -Ilib:test test/test_openapi_minitest.rb -n test_method_name`
+- **Lint:** `bundle exec rake standard`
+- **Lint autofix:** `bundle exec standardrb --fix`
+
+## Architecture
+
+The generation pipeline flows through four components in order:
+
+1. **DSL (`lib/openapi_minitest/dsl.rb`)** — Provides the `document_response` method mixed into test classes. Handles schema validation (optional) and normalization of Symbol schema references to `$ref` format.
+
+2. **ResultCollector (`lib/openapi_minitest/result_collector.rb`)** — Singleton that accumulates all recorded API calls during a test run. Stores two parallel hashes keyed by `"method /path"`: `@operations` (endpoint metadata) and `@responses` (grouped by HTTP status). Handles path normalization (e.g., `/api/users/123` → `/api/users/{user_id}`).
+
+3. **Generator (`lib/openapi_minitest/openapi/generator.rb`)** — Reads from ResultCollector and builds the complete OpenAPI 3.1.0 document hash. Handles path sorting, request body extraction, example merging, and security scheme attachment. Outputs YAML.
+
+4. **Railtie (`lib/openapi_minitest/railtie.rb`)** — Rails integration. Auto-includes DSL in `ActionDispatch::IntegrationTest`, registers `rails openapi:generate` rake task, and hooks into `Minitest.after_run` to trigger generation when `OPENAPI_GENERATE=true`.
+
+Configuration and schema registry live in `lib/openapi_minitest/configuration.rb`.
+
+## Test Setup
+
+Tests use `OpenapiMinitest::TestHelpers` (defined in `test/test_helper.rb`) which resets both configuration and the ResultCollector singleton in `setup`, ensuring test isolation.
+
+## Conventions
 
 - Use Conventional Commits format for all commit messages (e.g., `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`)

data/Makefile

@@ -6,12 +6,8 @@ install:
 console:
 	bin/console
 
-
 test:
 	bundle exec rake test
 
-
-
 lint-fix:
 	bundle exec standardrb --fix
-

data/README.md

@@ -155,6 +155,22 @@ OPENAPI_GENERATE=true rails test test/integration/
 rails openapi:generate
 ```
 
+### 5. Browse Documentation (optional)
+
+Run the install generator to add an API docs page powered by [Scalar](https://github.com/scalar/scalar):
+
+```bash
+rails generate openapi_minitest:install
+```
+
+This creates:
+
+- `app/controllers/api_docs_controller.rb` — serves the docs UI and the OpenAPI spec file
+- `app/views/api_docs/index.html.erb` — Scalar API reference page (titled with your Rails app name)
+- Routes: `GET /api-docs` and `GET /openapi.yml`
+
+Visit `/api-docs` in your browser to explore your API documentation interactively.
+
 ## API Reference
 
 ### Configuration Options

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OpenapiMinitest
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates an ApiDocsController and view for serving OpenAPI documentation with Scalar UI"
+
+      def copy_controller
+        template "api_docs_controller.rb.tt", "app/controllers/api_docs_controller.rb"
+      end
+
+      def copy_view
+        template "index.html.erb.tt", "app/views/api_docs/index.html.erb"
+      end
+
+      def add_routes
+        route <<~RUBY
+          get "api-docs" => "api_docs#index"
+          get "openapi.yml" => "api_docs#spec"
+        RUBY
+      end
+
+      private
+
+      def app_name
+        Rails.application.class.respond_to?(:module_parent_name) ? Rails.application.class.module_parent_name : Rails.application.class.parent_name
+      end
+    end
+  end
+end

data/lib/generators/openapi_minitest/install/templates/api_docs_controller.rb.tt

@@ -0,0 +1,9 @@
+class ApiDocsController < ApplicationController
+  def index
+    render layout: false
+  end
+
+  def spec
+    send_file Rails.root.join("doc/openapi.yml"), type: "text/yaml", disposition: "inline"
+  end
+end

data/lib/generators/openapi_minitest/install/templates/index.html.erb.tt

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title><%= app_name %> API Documentation</title>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+</head>
+<body>
+  <script id="api-reference" data-url="/openapi.yml"></script>
+  <script>
+    var configuration = {
+      theme: 'elysiajs',
+      expandAllResponses: true,
+      layout: 'modern',
+      defaultOpenAllTags: true,
+      hideClientButton: true,
+      showSidebar: true,
+      showDeveloperTools: 'localhost',
+      showToolbar: 'localhost',
+      operationTitleSource: 'summary',
+      persistAuth: false,
+      telemetry: true,
+      isEditable: false,
+      isLoading: false,
+      hideModels: false,
+      documentDownloadType: 'both',
+      hideTestRequestButton: false,
+      hideSearch: false,
+      showOperationId: false,
+      hideDarkModeToggle: false,
+      withDefaultFonts: true,
+      expandAllModelSections: false,
+      orderSchemaPropertiesBy: 'alpha',
+      orderRequiredPropertiesFirst: true,
+      _integration: 'html',
+      darkMode: true,
+      hiddenClients: ['unirest'],
+      defaultHttpClient: {
+        targetKey: 'ruby',
+        clientKey: 'faraday'
+      }
+    }
+    document.getElementById('api-reference').dataset.configuration = JSON.stringify(configuration)
+  </script>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+</body>
+</html>

data/lib/openapi_minitest/configuration.rb

@@ -10,7 +10,8 @@ module OpenapiMinitest
       :security_schemes,
       :tags,
       :validate_schema,
-      :strict_validation
+      :strict_validation,
+      :sort_paths
 
     def initialize
       @title = "API Documentation"
@@ -22,6 +23,7 @@ module OpenapiMinitest
       @tags = []
       @validate_schema = true
       @strict_validation = false
+      @sort_paths = :alphabetical
     end
   end
 

data/lib/openapi_minitest/openapi/generator.rb

@@ -63,7 +63,7 @@ module OpenapiMinitest
           paths[path][method] = build_operation(key, operation)
         end
 
-        paths
+        (@config.sort_paths == :alphabetical) ? paths.sort.to_h : paths
       end
 
       def build_operation(key, operation)

data/lib/openapi_minitest/result_collector.rb

@@ -1,61 +1,72 @@
 # frozen_string_literal: true
 
 require "singleton"
+require "monitor"
 require "json"
 
 module OpenapiMinitest
   class ResultCollector
     include Singleton
+    include MonitorMixin
 
     def initialize
+      super # MonitorMixin requires super
       reset!
     end
 
     def reset!
-      @operations = {}  # "METHOD /path" => operation data
-      @responses = {}   # "METHOD /path" => { status => [response_data] }
+      synchronize do
+        @operations = {}  # "METHOD /path" => operation data
+        @responses = {}   # "METHOD /path" => { status => [response_data] }
+      end
     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)
-      }
+      synchronize do
+        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
     end
 
-    attr_reader :operations
+    def operations
+      synchronize { @operations }
+    end
 
-    attr_reader :responses
+    def responses
+      synchronize { @responses }
+    end
 
     def empty?
-      @operations.empty?
+      synchronize { @operations.empty? }
     end
 
     private

data/lib/openapi_minitest/version.rb

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

data/release-please-config.json

@@ -9,8 +9,7 @@
       "bump-patch-for-minor-pre-major": true,
       "draft": false,
       "prerelease": false,
-      "version-file": "lib/openapi_minitest/version.rb",
-      "release-as": "0.1.0"
+      "version-file": "lib/openapi_minitest/version.rb"
     }
   },
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi_minitest
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Alex Koval
@@ -67,6 +67,9 @@ files:
 - Makefile
 - README.md
 - Rakefile
+- lib/generators/openapi_minitest/install/install_generator.rb
+- lib/generators/openapi_minitest/install/templates/api_docs_controller.rb.tt
+- lib/generators/openapi_minitest/install/templates/index.html.erb.tt
 - lib/openapi_minitest.rb
 - lib/openapi_minitest/configuration.rb
 - lib/openapi_minitest/dsl.rb