swagger_autogenerate 1.2.8 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7edebbaf56232cc63c6ba0084ae9536053f6b45f18763bc6718952da9e4b7e95
-  data.tar.gz: 91f05f795c8b81451d25c4997a08f176bc034a576e6a5db6c20782ae9c805cb2
+  metadata.gz: b2c5c12b58edcd185c9831efb1c2e2f01053281858e6ec0ae85c149a3f3a2f71
+  data.tar.gz: 1c6e7a1d15457fd89837315cbfaf5b41631047def4df33a5ba382d6c5382b3c3
 SHA512:
-  metadata.gz: 56e031eacfa7c2f47e2f35d652a68e059a56de0862b90a3af09574d186fddeef100becc70b52333a087209fe288d52adf3c54663f40c1caa5e4c3677057ef997
-  data.tar.gz: e7d9bcdc321318de22bed1f26af8119c27411254d47213bb86e01d29ac297853d9aa84f8caf797b3647235ed37c4b2e37778ea81791ee1e24902828fbce84c87
+  metadata.gz: 96261e06a8de505e0513f89c0aec39ca76ddf054412c117c29510310581312f5ca957184250e750f29a9b88674dc7ffa5e3a5abfa43d8f0e537504a078b3fe7f
+  data.tar.gz: 1f11a7ae9e1551f88fa2e4739f49edd4e3a1c5c7dc11004dc5a79721428622eee7dd05a10bfe7649f2863d4781efb1cf6d15915d2de16d90484774463eb8495c

data/CHANGELOG.md

@@ -1,24 +1,43 @@
 ## [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
+## [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,193 @@
-# 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 already use **`rswag-api`** and **`rswag-ui`**: run specs → YAML lands under `swagger/` (or `swagger/v1/`) → rswag serves and renders it.
+
+## 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
 
 ## 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
+- Optional but 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):
+Add to the test group:
 
-    ```
-    group :test do
-      gem 'swagger_autogenerate'
-    end
-    ```
-3) Install the gem and add to the application's Gemfile by executing:
-   ```
-   bundle install
-   ```
+```ruby
+group :test do
+  gem 'swagger_autogenerate'
+end
+```
 
-## Configuration
+```bash
+bundle install
+```
+
+### With rswag
+
+Typical Gemfile:
 
-To configure the swagger_autogenerate gem in your Rails application, follow these steps:
+```ruby
+gem 'rswag-api'
+gem 'rswag-ui'
 
-### Step 1:
-1) Open the app/controllers/application_controller.rb
-2) Inside the class ApplicationController block.
-3) Add the following code:
+group :test do
+  gem 'rspec-rails'
+  gem 'swagger_autogenerate'
+end
 ```
-    include SwaggerAutogenerate if Rails.env.test?
+
+Point rswag at the same folder this gem writes to (default `swagger` or `swagger/v1` when that directory exists).
+
+## Quick start
+
+### 1. Auto-include (default)
+
+In **test**, the gem Railtie includes itself into `ApplicationController` automatically.
+
+You can still include manually if you prefer:
+
+```ruby
+# app/controllers/application_controller.rb
+include SwaggerAutogenerate if Rails.env.test?
+```
+
+Disable auto-include:
+
+```ruby
+# config/initializers/swagger_autogenerate.rb
+SwaggerAutogenerate.configure do |config|
+  config.auto_include = false
+end
+```
+
+### 2. Generate docs from specs
+
+Write a normal file path (recommended with rswag):
+
+```bash
+SWAGGER_GENERATE_PATH='swagger/v1/swagger.yaml' bundle exec rspec spec/requests/users_spec.rb
 ```
 
-### 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
+Or generate one YAML file per controller tag under the default directory:
+
+```bash
+SWAGGER_GENERATE=1 bundle exec rspec spec/requests/
+# => swagger/users.yaml  (or swagger/v1/users.yaml when that folder exists / is configured)
 ```
+
+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.
+
+## Configuration
+
+Optional initializer — **only override what you need**. Defaults are project-agnostic (empty security, app name as title, `swagger` output path).
+
+```ruby
+# config/initializers/swagger_autogenerate.rb
 SwaggerAutogenerate.configure do |config|
-  config.with_config = true
-  config.with_multiple_examples = true
-  action_for_old_examples = :append # :replace or :append
-  config.with_response_description = true
+  # Where SWAGGER_GENERATE writes files (rswag default layout)
+  config.default_path = 'swagger/v1'
+
+  # 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' => [] }]
+
+  # 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
+```
+
+### 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' => {} }
+  }
+end
 ```
-$ This file is optional and allows you to customize the behavior of the gem by providing additional options.
+
+### 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
-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.
 
-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/employees_spec.rb
 ```
-SWAGGER_GENERATE_PATH='employee_apis.yaml' rspec spec/your_path/employees_controller_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
+
+```
+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
 ```
-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.
+## 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

data/lib/swagger_autogenerate/configuration.rb

@@ -1,31 +1,118 @@
+# frozen_string_literal: true
+
 module SwaggerAutogenerate
+  # Holds gem settings. Defaults work with any Rails app and rswag-api / rswag-ui.
+  #
+  # Override only what you need:
+  #
+  #   SwaggerAutogenerate.configure do |config|
+  #     config.default_path = 'swagger/v1'
+  #     config.info_title = 'My API'
+  #     config.security = [{ 'bearerAuth' => [] }]
+  #   end
+  #
   class Configuration
-    attr_accessor :with_config, :with_multiple_examples, :with_rspec_examples, :with_example_description,
-                  :with_response_description, :with_payload_properties, :swagger_path_environment_variable, :generate_swagger_environment_variable,
-                  :default_path, :environment_name, :security, :swagger_config, :response_status, :action_for_old_examples
+    ATTRS = %i[
+      with_config
+      with_multiple_examples
+      with_rspec_examples
+      with_example_description
+      with_response_description
+      with_payload_properties
+      swagger_path_environment_variable
+      generate_swagger_environment_variable
+      default_path
+      environment_name
+      security
+      swagger_config
+      response_status
+      action_for_old_examples
+      auto_include
+      info_title
+      info_description
+      info_version
+      openapi_version
+      servers
+      security_schemes
+    ].freeze
+
+    attr_accessor(*ATTRS)
 
     def initialize
+      apply_defaults!
+    end
+
+    def apply_defaults!
       @with_config = true
       @with_multiple_examples = true
       @with_rspec_examples = true
-      # remove this when we do not need it any more
       @with_example_description = true
       @with_payload_properties = true
       @with_response_description = true
       @action_for_old_examples = :append # :replace or :append
       @swagger_path_environment_variable = 'SWAGGER_GENERATE_PATH'
       @generate_swagger_environment_variable = 'SWAGGER_GENERATE'
-      @default_path = 'swagger'
+      @default_path = nil # resolved lazily (rswag-aware)
       @environment_name = :test
-      @security = default_security
-      @swagger_config = default_swagger_config
+      @auto_include = true
+      @security = []
       @response_status = default_response_status
+      @swagger_config = nil # resolved lazily
+      @info_title = nil
+      @info_description = 'API documentation generated from request specs'
+      @info_version = '1.0.0'
+      @openapi_version = '3.0.1'
+      @servers = []
+      @security_schemes = {}
+    end
+
+    # Directory under Rails.root where YAML files are written.
+    # Prefers rswag swagger root when available, otherwise "swagger".
+    def resolved_default_path
+      explicit = @default_path
+      return explicit if explicit.present?
+
+      rswag_path || 'swagger'
+    end
+
+    def resolved_swagger_config
+      return @swagger_config if @swagger_config.present?
+
+      {
+        'openapi' => openapi_version,
+        'info' => {
+          'title' => resolved_info_title,
+          'description' => info_description,
+          'version' => info_version
+        },
+        'servers' => servers,
+        'components' => {
+          'securitySchemes' => security_schemes
+        }
+      }
+    end
+
+    def resolved_info_title
+      return info_title if info_title.present?
+
+      app_class = defined?(Rails) && Rails.respond_to?(:application) && Rails.application&.class
+      return 'API' unless app_class
+
+      if app_class.respond_to?(:module_parent_name)
+        app_class.module_parent_name
+      elsif app_class.respond_to?(:parent_name)
+        app_class.parent_name
+      else
+        'API'
+      end
+    rescue StandardError
+      'API'
     end
 
     def default_response_status
       {
         100 => 'The initial part of the request has been received, and the client should proceed with sending the remainder of the request',
-        101 => 'The server agrees to switch protocols and is acknowledging the client\'s request to change the protocol being used',
+        101 => "The server agrees to switch protocols and is acknowledging the client's request to change the protocol being used",
         200 => 'The request has succeeded',
         201 => 'The request has been fulfilled, and a new resource has been created as a result. The newly created resource is returned in the response body',
         202 => 'The request has been accepted for processing, but the processing has not been completed. The response may contain an estimated completion time or other status information',
@@ -48,32 +135,18 @@ module SwaggerAutogenerate
       }
     end
 
-    def default_swagger_config
-      {
-        'openapi' => '3.0.0',
-        'info' => {
-          'title' => 'title',
-          'description' => 'description',
-          'version' => '1.0.0'
-        },
-        'servers' => [],
-        'components' => {
-          'securitySchemes' => {
-            'locale' => {
-              'type' => 'apiKey',
-              'in' => 'query',
-              'name' => 'locale'
-            }
-          }
-        }
-      }
-    end
+    private
+
+    def rswag_path
+      return unless defined?(Rails) && Rails.root
 
-    def default_security
-      [
-        { 'org_slug' => [] },
-        { 'locale' => [] }
-      ]
+      # Common rswag layout: swagger/v1/swagger.yaml
+      return 'swagger/v1' if Rails.root.join('swagger/v1').directory?
+      return 'swagger' if Rails.root.join('swagger').directory?
+
+      nil
+    rescue StandardError
+      nil
     end
   end
 
@@ -84,4 +157,8 @@ module SwaggerAutogenerate
   def self.configure
     yield(configuration)
   end
+
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
 end

data/lib/swagger_autogenerate/document_writer.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module SwaggerAutogenerate
+  # Resolves output path and reads/writes Swagger YAML documents.
+  class DocumentWriter
+    def initialize(config:, tags:, request:)
+      @config = config
+      @tags = tags
+      @request = request
+    end
+
+    def location
+      return @location if defined?(@location)
+
+      generate_env = config.generate_swagger_environment_variable
+      path_env = config.swagger_path_environment_variable
+
+      @location =
+        if ENV[generate_env].present?
+          directory = Rails.root.join(config.resolved_default_path).to_s
+          FileUtils.mkdir_p(directory)
+          File.join(directory, "#{Helpers.snake_case(tags&.first)}.yaml")
+        elsif ENV[path_env].to_s.match?(/\.(ya?ml)\z/i)
+          Rails.root.join(ENV.fetch(path_env)).to_s
+        else
+          directory = Rails.root.join(ENV.fetch(path_env, config.resolved_default_path)).to_s
+          FileUtils.mkdir_p(directory)
+          File.join(directory, "#{Helpers.snake_case(tags&.first)}.yaml")
+        end
+    end
+
+    def exist?
+      File.exist?(location)
+    end
+
+    def read
+      return nil unless exist?
+
+      Helpers.load_yaml(location)
+    end
+
+    def write(data)
+      File.write(location, Helpers.dump_yaml(data))
+    end
+
+    def ensure_exists!
+      write({ 'paths' => {} }) unless exist?
+    end
+
+    private
+
+    attr_reader :config, :tags, :request
+  end
+end