swagger_autogenerate 1.2.9 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dafd89e33e58235dea22170057658250e81904936e750d53990d91e2de2f624c
-  data.tar.gz: d52401f1dd5aaeaef3a0fbf37ec9d78c924f3b78b2ef529f8169c50ce009566a
+  metadata.gz: 82b7c6523f9a6f361c4f78be66068aab528b9707419a11ae61b5264878706ef1
+  data.tar.gz: f7671a245cb3a4a89452db82f6d5ba48a1f5b810c1a52d2323cee1a94f76726a
 SHA512:
-  metadata.gz: 9c25c49469a803b38ce2e06804ab3c9eeeb74deceb8153c4291d7c988ebf66066ac9eda0213b25a83bbb1645ff7c6de4f5f56445061e3650fd1226b94948640e
-  data.tar.gz: 87d9405997af4cadb9cdfc552ff9bffc89fb65caa22c725d4248253264a50e9aa53dbfd1c18d78ffe5fe19cd0824ee2e5cd8836a73d3e607abb79ae41ba2e906
+  metadata.gz: 2e4b21d768fcbd45e6a082f3caf0c437079d535d53c5fa9466aa1c7b70c69e289de2fadc9d440d2c9128cfbcf99dabeb1cf1f5742154ede03d203cc86c3a8cac
+  data.tar.gz: 4e0b9ce2a3cc3d9dae32383b8980d4b31e70b0f7611c8e3769e0ef7360da94e42ef060aa62860366698fafdb8bd0dbdf3b2bc475e4ad6d257b5f41a2c202c8eb

data/CHANGELOG.md

@@ -1,25 +1,47 @@
 ## [Unreleased]
 
-## [0.1.1] - 2024-05-27
-## [1.0.2] - 2024-05-31
-## [1.0.3] - 2024-05-31
-## [1.0.4] - 2024-06-01
-## [1.0.5] - 2024-06-01
-## [1.0.6] - 2024-06-01
-## [1.0.7] - 2024-06-01
-## [1.0.8] - 2024-06-03
-## [1.0.9] - 2024-06-04
-## [1.1.0] - 2024-06-23
-## [1.1.1] - 2024-06-26
-## [1.1.2] - 2024-08-17
-## [1.2.0] - 2024-09-08
-## [1.2.1] - 2024-09-08
-## [1.2.2] - 2024-09-12
-## [1.2.3] - 2024-09-12
-## [1.2.4] - 2024-09-15
-## [1.2.5] - 2024-09-15
-## [1.2.6] - 2024-11-05
-## [1.2.8] - 2024-11-05
+### 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
+- Default `security` is now `[]` (no project-specific `org_slug` / `locale` schemes)
+- Default OpenAPI document is built from app name + empty `securitySchemes`
+- Env-gated generation helpers renamed conceptually to `SwaggerAutogenerate.generate?` (`allow_swagger?` still works)
+- Internal code split into focused classes (public configure API unchanged in spirit)
+
+### Added
+- Railtie auto-includes into `ApplicationController` in the configured test environment
+- RSpec test suite for configuration, helpers, schema/params/responses, and YAML generation
+- rswag-friendly `default_path` resolution (`swagger` / `swagger/v1`)
+- Ergonomic config: `info_title`, `servers`, `security_schemes`, `auto_include`
+
+### Improved
+- README for rswag-api / rswag-ui usage
+- Clearer module layout under `lib/swagger_autogenerate/`
+
 ## [1.2.9] - 2025-11-24
+## [1.2.8] - 2024-11-05
+## [1.2.6] - 2024-11-05
+## [1.2.5] - 2024-09-15
+## [1.2.4] - 2024-09-15
+## [1.2.3] - 2024-09-12
+## [1.2.2] - 2024-09-12
+## [1.2.1] - 2024-09-08
+## [1.2.0] - 2024-09-08
+## [1.1.2] - 2024-08-17
+## [1.1.1] - 2024-06-26
+## [1.1.0] - 2024-06-23
+## [1.0.9] - 2024-06-04
+## [1.0.8] - 2024-06-03
+## [1.0.7] - 2024-06-01
+## [1.0.6] - 2024-06-01
+## [1.0.5] - 2024-06-01
+## [1.0.4] - 2024-06-01
+## [1.0.3] - 2024-05-31
+## [1.0.2] - 2024-05-31
+## [0.1.1] - 2024-05-27
 
 - Initial release

data/README.md

@@ -1,77 +1,381 @@
-# SwaggerAutogenerate
-automating Swagger YAML generation in Ruby on Rails offers a range of benefits for API documentation. By leveraging the power of the swagger_autogenerate gem, developers can:
-1) save time and effort
-2) (up to date) reducing the chances of inconsistencies between the actual API implementation and its documentation.
-3) improves the overall development workflow by providing a seamless integration with testing frameworks like RSpec.
-4) resulting in better communication and understanding of the APIs.
+# Swagger Autogenerate
 
-The gem automatically observes the request/response patterns during the execution of test scenarios, generating accurate Swagger YAML files that reflect the API's behavior. developers and consumers can better understand and interact with the APIs.
+Generate **OpenAPI / Swagger YAML** from your existing Rails RSpec request (or controller) specs.
+
+Designed to drop into projects that use **`rswag-api`** and **`rswag-ui`**:
+
+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
 
-The SwaggerAutogenerate gem depends on the rspec-rails gem, which brings the RSpec testing framework to Ruby on Rails.
-Please install rspec-rails first: https://github.com/rspec/rspec-rails
-Then continue the installation process.
+- Ruby `>= 2.7`
+- Rails `>= 5.2`
+- [rspec-rails](https://github.com/rspec/rspec-rails) in the host app
+- Recommended: [`rswag-api`](https://github.com/rswag/rswag) + [`rswag-ui`](https://github.com/rswag/rswag)
 
 ## Installation
 
-1) Open your Gemfile located at ./Gemfile
-2) Add the following line to the Gemfile within the appropriate group (e.g., :test):
+```ruby
+# Gemfile
+gem 'rswag-api'
+gem 'rswag-ui'
 
-    ```
-    group :test do
-      gem 'swagger_autogenerate'
-    end
-    ```
-3) Install the gem and add to the application's Gemfile by executing:
-   ```
-   bundle install
-   ```
+group :test do
+  gem 'rspec-rails'
+  gem 'swagger_autogenerate'
+end
+```
 
-## Configuration
+```bash
+bundle install
+```
 
-To configure the swagger_autogenerate gem in your Rails application, follow these steps:
+Then add the host-app files below (copy-paste and adjust titles / URLs for your API).
 
-### Step 1:
-1) Open the app/controllers/application_controller.rb
-2) Inside the class ApplicationController block.
-3) Add the following code:
-```
-    include SwaggerAutogenerate if Rails.env.test?
+---
+
+## Host app setup (required for rswag UI)
+
+### 1. Mount rswag in `config/routes.rb`
+
+```ruby
+mount Rswag::Ui::Engine => "/api-docs"
+mount Rswag::Api::Engine => "/api-docs"
 ```
 
-### Step 2 (optional)
-1) Create a file called swagger_autogenerate.rb in the ./config/initializers
-2) Open the ./config/initializers/swagger_autogenerate.rb
-3) Add the following code to the swagger_autogenerate.rb
+### 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
 ```
+
+### 3. `config/initializers/swagger_autogenerate.rb`
+
+Guard with `defined?` so `rails s` does not crash when the gem is only in the `:test` group.
+
+```ruby
+# frozen_string_literal: true
+
+# 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"
+
+  # 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
-  action_for_old_examples = :append # :replace or :append
+  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
+# 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
+```
+
+#### `config/initializers/combine_swagger.rb`
+
+Rebuilds the combined file on every boot so `/api-docs` stays fresh.
+
+```ruby
+# 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
+```
+
+#### `bin/combine_swagger`
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/swagger_combiner"
+
+SwaggerCombiner.combine!
+```
+
+```bash
+chmod +x bin/combine_swagger
+```
+
+---
+
+## 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/
+
+# Then combine into swagger/v1/swagger.yaml
+bin/combine_swagger
+# or: bundle exec rake swagger:combine
 ```
-$ This file is optional and allows you to customize the behavior of the gem by providing additional options.
 
-## Example
-To generate Swagger YAML documentation for the APIs implemented in the EmployeesController class, you can follow these steps:
-1) Ensure that you have the swagger_autogenerate gem installed and configured in your Rails application, as described later.
-2) Create a spec file for the EmployeesController class at the path:
-$ spec/your_path/employees_controller_spec.rb
-This file should contain the test scenarios for each action (e.g., index, show, create) of the controller.
+Or write a single file directly:
 
-3) Run the spec code using the rspec command and set the environment variable SWAGGER to the desired YAML file name. For example:
+```bash
+SWAGGER_GENERATE_PATH='swagger/v1/swagger.yaml' bundle exec rspec spec/requests/users_spec.rb
 ```
-SWAGGER_GENERATE_PATH='employee_apis.yaml' rspec spec/your_path/employees_controller_spec.rb
+
+Generation only runs when:
+
+1. `SWAGGER_GENERATE_PATH` or `SWAGGER_GENERATE` is set, and
+2. `Rails.env` matches `config.environment_name` (default `:test`)
+
+Without those env vars, specs run normally and nothing is written.
+
+Open the UI: `http://localhost:3000/api-docs`
+
+### 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
+config.auto_include = false
 ```
-4) This command runs the spec file and instructs the swagger_autogenerate gem to generate Swagger YAML documentation and save it to the file named employee_apis.yaml.
-5) Once the command finishes executing, you will have the Swagger YAML documentation generated based on the test scenarios in the employees_controller_spec.rb file.
 
-### Please note 
-that the generated documentation will depend on the test scenarios defined in your employees_controller_spec.rb  file. Make sure to have comprehensive test scenarios that cover  different scenarios and expected responses for accurate and detailed  Swagger documentation.
+---
+
+## Configuration reference
+
+Only override what you need. Defaults are project-agnostic (empty security, app name as title, `swagger` output path).
+
+### Full document override
+
+```ruby
+SwaggerAutogenerate.configure do |config|
+  config.swagger_config = {
+    "openapi" => "3.0.1",
+    "info" => { "title" => "Custom", "version" => "1.0.0" },
+    "components" => { "securitySchemes" => {} }
+  }
+end
+```
+
+## Library layout
+
+```
+lib/swagger_autogenerate/
+  configuration.rb      # defaults + customization
+  swagger_trace.rb      # orchestrates one request/response
+  path_normalizer.rb    # /users/1 → /users/{id}
+  parameter_builder.rb  # parameters + requestBody
+  response_builder.rb   # responses + examples
+  schema_builder.rb     # type inference
+  document_writer.rb    # read/write YAML
+  yaml_merger.rb        # merge into existing document
+  helpers.rb
+  railtie.rb            # auto-include in test
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT — see [LICENSE.txt](LICENSE.txt).

data/examples/swagger_autogenerate.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Copy to config/initializers/swagger_autogenerate.rb and adjust as needed.
+# Everything is optional — omit this file to use project-agnostic defaults.
+
+SwaggerAutogenerate.configure do |config|
+  # rswag-api / rswag-ui usually serve files from swagger/v1
+  config.default_path = 'swagger/v1'
+
+  config.info_title = 'My API'
+  config.info_description = 'API documentation generated from request specs'
+  config.info_version = '1.0.0'
+  config.servers = [{ 'url' => 'http://localhost:3000' }]
+
+  # Example JWT security for OpenAPI / rswag-ui "Authorize"
+  # config.security_schemes = {
+  #   'bearerAuth' => {
+  #     'type' => 'http',
+  #     'scheme' => 'bearer',
+  #     'bearerFormat' => 'JWT'
+  #   }
+  # }
+  # config.security = [{ 'bearerAuth' => [] }]
+
+  config.with_multiple_examples = true
+  config.with_rspec_examples = true
+  config.action_for_old_examples = :append # :replace
+end