swagger_autogenerate 2.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2c5c12b58edcd185c9831efb1c2e2f01053281858e6ec0ae85c149a3f3a2f71
-  data.tar.gz: 1c6e7a1d15457fd89837315cbfaf5b41631047def4df33a5ba382d6c5382b3c3
+  metadata.gz: 82b7c6523f9a6f361c4f78be66068aab528b9707419a11ae61b5264878706ef1
+  data.tar.gz: f7671a245cb3a4a89452db82f6d5ba48a1f5b810c1a52d2323cee1a94f76726a
 SHA512:
-  metadata.gz: 96261e06a8de505e0513f89c0aec39ca76ddf054412c117c29510310581312f5ca957184250e750f29a9b88674dc7ffa5e3a5abfa43d8f0e537504a078b3fe7f
-  data.tar.gz: 1f11a7ae9e1551f88fa2e4739f49edd4e3a1c5c7dc11004dc5a79721428622eee7dd05a10bfe7649f2863d4781efb1cf6d15915d2de16d90484774463eb8495c
+  metadata.gz: 2e4b21d768fcbd45e6a082f3caf0c437079d535d53c5fa9466aa1c7b70c69e289de2fadc9d440d2c9128cfbcf99dabeb1cf1f5742154ede03d203cc86c3a8cac
+  data.tar.gz: 4e0b9ce2a3cc3d9dae32383b8980d4b31e70b0f7611c8e3769e0ef7360da94e42ef060aa62860366698fafdb8bd0dbdf3b2bc475e4ad6d257b5f41a2c202c8eb

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+### Improved
+- README documents full Rails + rswag host setup (routes, initializers, SwaggerCombiner, rake/bin)
+
+## [2.0.1] - 2026-09-03
 ## [2.0.0] - 2026-09-03
 
 ### Breaking

data/README.md

@@ -2,27 +2,28 @@
 
 Generate **OpenAPI / Swagger YAML** from your existing Rails RSpec request (or controller) specs.
 
-Designed to drop into projects that already use **`rswag-api`** and **`rswag-ui`**: run specs → YAML lands under `swagger/` (or `swagger/v1/`) → rswag serves and renders it.
+Designed to drop into projects that use **`rswag-api`** and **`rswag-ui`**:
 
-## Why
-
-- Keep docs in sync with real request/response behavior from tests
-- No hand-maintained path definitions for happy-path coverage
-- Works with any Rails app; rswag-friendly defaults out of the box
+1. Run specs with `SWAGGER_GENERATE=1` → one YAML fragment per resource under `swagger/v1/`
+2. Combine fragments into `swagger/v1/swagger.yaml`
+3. Rswag serves that file at `/api-docs`
 
 ## Dependencies
 
 - Ruby `>= 2.7`
 - Rails `>= 5.2`
 - [rspec-rails](https://github.com/rspec/rspec-rails) in the host app
-- Optional but recommended: [`rswag-api`](https://github.com/rswag/rswag) + [`rswag-ui`](https://github.com/rswag/rswag)
+- Recommended: [`rswag-api`](https://github.com/rswag/rswag) + [`rswag-ui`](https://github.com/rswag/rswag)
 
 ## Installation
 
-Add to the test group:
-
 ```ruby
+# Gemfile
+gem 'rswag-api'
+gem 'rswag-ui'
+
 group :test do
+  gem 'rspec-rails'
   gem 'swagger_autogenerate'
 end
 ```
@@ -31,57 +32,278 @@ end
 bundle install
 ```
 
-### With rswag
+Then add the host-app files below (copy-paste and adjust titles / URLs for your API).
+
+---
 
-Typical Gemfile:
+## Host app setup (required for rswag UI)
+
+### 1. Mount rswag in `config/routes.rb`
 
 ```ruby
-gem 'rswag-api'
-gem 'rswag-ui'
+mount Rswag::Ui::Engine => "/api-docs"
+mount Rswag::Api::Engine => "/api-docs"
+```
 
-group :test do
-  gem 'rspec-rails'
-  gem 'swagger_autogenerate'
+### 2. `config/initializers/rswag_api.rb`
+
+Serves `swagger/v1/swagger.yaml` at `/api-docs/v1/swagger.yaml`.
+
+```ruby
+# frozen_string_literal: true
+
+Rswag::Api.configure do |c|
+  # Serves files from swagger/ — so swagger/v1/swagger.yaml → /api-docs/v1/swagger.yaml
+  c.openapi_root = Rails.root.join("swagger").to_s
+end
+
+Rswag::Ui.configure do |c|
+  c.openapi_endpoint "/api-docs/v1/swagger.yaml", "My API V1"
 end
 ```
 
-Point rswag at the same folder this gem writes to (default `swagger` or `swagger/v1` when that directory exists).
+### 3. `config/initializers/swagger_autogenerate.rb`
 
-## Quick start
+Guard with `defined?` so `rails s` does not crash when the gem is only in the `:test` group.
 
-### 1. Auto-include (default)
+```ruby
+# frozen_string_literal: true
 
-In **test**, the gem Railtie includes itself into `ApplicationController` automatically.
+# swagger_autogenerate is only loaded in the test (and optionally development) group.
+# Guard so `rails s` in development does not crash when the gem is not required.
+return unless defined?(SwaggerAutogenerate)
+
+SwaggerAutogenerate.configure do |config|
+  # Where SWAGGER_GENERATE writes files (rswag default layout)
+  config.default_path = "swagger/v1"
 
-You can still include manually if you prefer:
+  # OpenAPI info
+  config.info_title = "My API"
+  config.info_description = "Public HTTP API"
+  config.info_version = "1.0.0"
+  config.openapi_version = "3.0.1"
+  config.servers = [{ "url" => "http://localhost:3000" }]
+
+  # Auth for rswag / OpenAPI (optional — remove if you have no auth)
+  config.security_schemes = {
+    "bearerAuth" => {
+      "type" => "http",
+      "scheme" => "bearer",
+      "bearerFormat" => "JWT"
+    }
+  }
+  config.security = [{ "bearerAuth" => [] }]
+
+  # Behavior flags
+  config.with_config = true
+  config.with_multiple_examples = true
+  config.with_rspec_examples = true
+  config.with_response_description = true
+  config.with_payload_properties = true
+  config.action_for_old_examples = :append
+
+  # Env var names / environment gate
+  config.swagger_path_environment_variable = "SWAGGER_GENERATE_PATH"
+  config.generate_swagger_environment_variable = "SWAGGER_GENERATE"
+  config.environment_name = :test
+  config.auto_include = true
+end
+```
+
+### 4. Combine fragments → single `swagger.yaml`
+
+`SWAGGER_GENERATE=1` writes **one file per resource** (e.g. `swagger/v1/users.yaml`). Rswag UI expects a **single** file at `swagger/v1/swagger.yaml`. Add a small combiner in the host app.
+
+#### `lib/swagger_combiner.rb`
 
 ```ruby
-# app/controllers/application_controller.rb
-include SwaggerAutogenerate if Rails.env.test?
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+# Merges every OpenAPI fragment under swagger/v1/*.yaml (except swagger.yaml)
+# into a single swagger/v1/swagger.yaml for Rswag UI.
+module SwaggerCombiner
+  module_function
+
+  SOURCE_DIR = File.expand_path("../swagger/v1", __dir__)
+  OUTPUT_FILE = File.join(SOURCE_DIR, "swagger.yaml")
+  SKIP_BASENAMES = %w[swagger.yaml swagger.yml].freeze
+
+  DEFAULT_DOC = {
+    "openapi" => "3.0.1",
+    "info" => {
+      "title" => "My API",
+      "description" => "Public HTTP API",
+      "version" => "1.0.0"
+    },
+    "servers" => [
+      { "url" => "http://localhost:3000" }
+    ],
+    "components" => {
+      "securitySchemes" => {
+        "bearerAuth" => {
+          "type" => "http",
+          "scheme" => "bearer",
+          "bearerFormat" => "JWT"
+        }
+      }
+    },
+    "security" => [
+      { "bearerAuth" => [] }
+    ],
+    "paths" => {}
+  }.freeze
+
+  def combine!(source_dir: SOURCE_DIR, output_file: OUTPUT_FILE)
+    FileUtils.mkdir_p(source_dir)
+
+    fragments = Dir[File.join(source_dir, "*.{yaml,yml}")]
+                  .reject { |path| SKIP_BASENAMES.include?(File.basename(path)) }
+                  .sort
+
+    if fragments.empty?
+      warn "[SwaggerCombiner] no fragment files found in #{source_dir}"
+      write_yaml(output_file, DEFAULT_DOC.dup)
+      return output_file
+    end
+
+    merged = deep_dup(DEFAULT_DOC)
+
+    fragments.each do |path|
+      doc = load_yaml(path)
+      next unless doc.is_a?(Hash)
+
+      merged["paths"] = deep_merge(merged["paths"], stringify_keys(doc["paths"] || {}))
+      merged["components"] = deep_merge(merged["components"], stringify_keys(doc["components"] || {}))
+
+      if doc["tags"].is_a?(Array)
+        merged["tags"] = Array(merged["tags"]) | doc["tags"]
+      end
+    end
+
+    merged["paths"] = merged["paths"].sort.to_h
+
+    write_yaml(output_file, merged)
+    puts "[SwaggerCombiner] wrote #{output_file} (#{merged["paths"].size} paths from #{fragments.size} files)"
+    output_file
+  end
+
+  def load_yaml(path)
+    YAML.safe_load(
+      File.read(path),
+      permitted_classes: [Date, Time, Symbol],
+      aliases: true
+    )
+  rescue Psych::DisallowedClass, Psych::BadAlias
+    YAML.load_file(path) # fragments may contain complex examples
+  end
+
+  def write_yaml(path, data)
+    File.write(path, data.to_yaml)
+  end
+
+  def deep_merge(left, right)
+    left = {} unless left.is_a?(Hash)
+    right = {} unless right.is_a?(Hash)
+
+    left.merge(right) do |_key, old_val, new_val|
+      if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+        deep_merge(old_val, new_val)
+      else
+        new_val.nil? ? old_val : new_val
+      end
+    end
+  end
+
+  def stringify_keys(value)
+    case value
+    when Hash
+      value.each_with_object({}) do |(k, v), memo|
+        memo[k.to_s] = stringify_keys(v)
+      end
+    when Array
+      value.map { |item| stringify_keys(item) }
+    else
+      value
+    end
+  end
+
+  def deep_dup(value)
+    Marshal.load(Marshal.dump(value))
+  end
+end
 ```
 
-Disable auto-include:
+#### `config/initializers/combine_swagger.rb`
+
+Rebuilds the combined file on every boot so `/api-docs` stays fresh.
 
 ```ruby
-# config/initializers/swagger_autogenerate.rb
-SwaggerAutogenerate.configure do |config|
-  config.auto_include = false
+# frozen_string_literal: true
+
+# Rebuild swagger/v1/swagger.yaml from per-resource fragments on every boot.
+# Rswag UI expects a single file at /api-docs/v1/swagger.yaml.
+begin
+  require Rails.root.join("lib/swagger_combiner")
+  SwaggerCombiner.combine!(
+    source_dir: Rails.root.join("swagger/v1").to_s,
+    output_file: Rails.root.join("swagger/v1/swagger.yaml").to_s
+  )
+rescue StandardError => e
+  warn "[SwaggerCombiner] failed to combine OpenAPI docs: #{e.class}: #{e.message}"
+end
+```
+
+#### `lib/tasks/swagger.rake`
+
+```ruby
+# frozen_string_literal: true
+
+namespace :swagger do
+  desc "Combine swagger/v1/*.yaml fragments into swagger/v1/swagger.yaml"
+  task combine: :environment do
+    require Rails.root.join("lib/swagger_combiner")
+    SwaggerCombiner.combine!
+  end
 end
 ```
 
-### 2. Generate docs from specs
+#### `bin/combine_swagger`
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-Write a normal file path (recommended with rswag):
+require_relative "../lib/swagger_combiner"
+
+SwaggerCombiner.combine!
+```
 
 ```bash
-SWAGGER_GENERATE_PATH='swagger/v1/swagger.yaml' bundle exec rspec spec/requests/users_spec.rb
+chmod +x bin/combine_swagger
 ```
 
-Or generate one YAML file per controller tag under the default directory:
+---
+
+## Generate docs
+
+In **test**, the gem Railtie includes itself into `ApplicationController` automatically.
 
 ```bash
+# One YAML fragment per controller tag under swagger/v1/
 SWAGGER_GENERATE=1 bundle exec rspec spec/requests/
-# => swagger/users.yaml  (or swagger/v1/users.yaml when that folder exists / is configured)
+
+# Then combine into swagger/v1/swagger.yaml
+bin/combine_swagger
+# or: bundle exec rake swagger:combine
+```
+
+Or write a single file directly:
+
+```bash
+SWAGGER_GENERATE_PATH='swagger/v1/swagger.yaml' bundle exec rspec spec/requests/users_spec.rb
 ```
 
 Generation only runs when:
@@ -91,80 +313,46 @@ Generation only runs when:
 
 Without those env vars, specs run normally and nothing is written.
 
-## Configuration
+Open the UI: `http://localhost:3000/api-docs`
 
-Optional initializer — **only override what you need**. Defaults are project-agnostic (empty security, app name as title, `swagger` output path).
+### Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `SWAGGER_GENERATE_PATH` | Exact `.yaml`/`.yml` file **or** a directory (one file per tag) |
+| `SWAGGER_GENERATE` | Write under `config.default_path` (rswag-aware) |
+| `tag` | Optional override for the OpenAPI tag / filename stem |
+
+### Manual include / disable auto-include
+
+```ruby
+# app/controllers/application_controller.rb
+include SwaggerAutogenerate if Rails.env.test?
+```
 
 ```ruby
 # config/initializers/swagger_autogenerate.rb
-SwaggerAutogenerate.configure do |config|
-  # Where SWAGGER_GENERATE writes files (rswag default layout)
-  config.default_path = 'swagger/v1'
+config.auto_include = false
+```
 
-  # OpenAPI info (auto title = Rails app module name when unset)
-  config.info_title = 'My API'
-  config.info_description = 'Public HTTP API'
-  config.info_version = '1.0.0'
-  config.openapi_version = '3.0.1'
-  config.servers = [{ 'url' => 'https://api.example.com' }]
+---
 
-  # Auth for rswag / OpenAPI
-  config.security_schemes = {
-    'bearerAuth' => {
-      'type' => 'http',
-      'scheme' => 'bearer',
-      'bearerFormat' => 'JWT'
-    }
-  }
-  config.security = [{ 'bearerAuth' => [] }]
+## Configuration reference
 
-  # Behavior flags
-  config.with_config = true                 # write openapi/info/components header
-  config.with_multiple_examples = true      # keep several response examples per status
-  config.with_rspec_examples = true         # use RSpec example group description as example name
-  config.with_response_description = true   # human-readable status descriptions
-  config.with_payload_properties = true     # document request payload shapes per example
-  config.action_for_old_examples = :append  # or :replace
-
-  # Env var names / environment gate (rarely changed)
-  config.swagger_path_environment_variable = 'SWAGGER_GENERATE_PATH'
-  config.generate_swagger_environment_variable = 'SWAGGER_GENERATE'
-  config.environment_name = :test
-  config.auto_include = true
-end
-```
+Only override what you need. Defaults are project-agnostic (empty security, app name as title, `swagger` output path).
 
 ### Full document override
 
-If you already maintain a root OpenAPI hash (or want zero magic):
-
 ```ruby
 SwaggerAutogenerate.configure do |config|
   config.swagger_config = {
-    'openapi' => '3.0.1',
-    'info' => { 'title' => 'Custom', 'version' => '1.0.0' },
-    'components' => { 'securitySchemes' => {} }
+    "openapi" => "3.0.1",
+    "info" => { "title" => "Custom", "version" => "1.0.0" },
+    "components" => { "securitySchemes" => {} }
   }
 end
 ```
 
-### Environment variables
-
-| Variable | Purpose |
-|---|---|
-| `SWAGGER_GENERATE_PATH` | Exact `.yaml`/`.yml` file **or** a directory (one file per tag) |
-| `SWAGGER_GENERATE` | Write under `config.default_path` (rswag-aware) |
-| `tag` | Optional override for the OpenAPI tag / filename stem |
-
-## Example
-
-```bash
-SWAGGER_GENERATE_PATH='swagger/v1/swagger.yaml' \
-  bundle exec rspec spec/requests/employees_spec.rb
-```
-
-Coverage in the YAML matches what your examples actually hit (paths, statuses, bodies, query/path params). Prefer request specs that exercise real routes.
-
 ## Library layout
 
 ```

data/lib/swagger_autogenerate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwaggerAutogenerate
-  VERSION = '2.0.0'
+  VERSION = '2.0.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swagger_autogenerate
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.1
 platform: ruby
 authors:
 - MohammedBuraiah