routes_api_spec_generator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f58458c8891010c8773f1701fb8f8b7d1ba98eb5faf24c5fa67abcf82e214153
+  data.tar.gz: '094794045e0f83ad55ac08ee3ebcd7a9006ee48e5f8ef877297bd6bf55250a5b'
+SHA512:
+  metadata.gz: 5908ac4e089e60052dbe987ed96ddf9173375b1e010eb4e589254de07d943635fe9ad51d1e720a3eabe8b6c9488b06cb0fea8572aea90c61414af8b37930cd61
+  data.tar.gz: ebeb96493e737cbdb7b9cf882a7dcde4ecf126296ca7b7b657769bb4b8b1bdbd976e030bad2ab1ede3134cea830f44277ce001df451d59bcee681cc98163fe28

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-09
+
+### Added
+
+- Coletor de rotas Rails (`/api/v1` por default)
+- Inspector de controllers (services, tenant header, template)
+- Loader de config YAML opcional
+- Generator com templates ERB (channels, big_numbers, insights, general_metrics)
+- CLI `routes-api-spec-generator`
+- Rake task `routes_api_spec:generate` via Railtie

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saulo Filho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,129 @@
+# routes_api_spec_generator
+
+[![Gem Version](https://badge.fury.io/rb/routes_api_spec_generator.svg)](https://badge.fury.io/rb/routes_api_spec_generator)
+
+**Site:** [saulofilho.github.io/routes-api-spec-generator](https://saulofilho.github.io/routes-api-spec-generator/)
+
+Gera **request specs RSpec com rswag** a partir de **rotas Rails** e inspeção de controllers.
+
+Ferramenta open source para times que usam o fluxo **spec → swagger** (`rake rswag:specs:swaggerize`) e querem reduzir o boilerplate ao cobrir novos endpoints.
+
+## O que ela faz
+
+- Lê rotas Rails (ex.: `/api/v1/*`)
+- Inspeciona controllers para inferir services, headers de tenant e parâmetros
+- Aplica overrides opcionais via `config/routes_api_spec_generator.yml`
+- Materializa arquivos em `spec/requests/**/_spec.rb` via templates ERB
+
+## O que ela NÃO faz
+
+- Gerar specs a partir do Swagger (fluxo circular no rswag)
+- Substituir mocks ou schemas detalhados específicos do seu domínio
+- Rodar testes ou publicar o contrato OpenAPI automaticamente
+
+## Instalação
+
+```bash
+gem install routes_api_spec_generator
+```
+
+Ou no `Gemfile` de um app Rails:
+
+```ruby
+group :development, :test do
+  gem 'routes_api_spec_generator'
+end
+```
+
+## Uso via Rake (app Rails)
+
+```bash
+bundle exec rake routes_api_spec:generate
+FORCE=true bundle exec rake routes_api_spec:generate   # sobrescreve existentes
+DRY_RUN=true bundle exec rake routes_api_spec:generate # apenas lista
+```
+
+## Uso via CLI
+
+```bash
+routes-api-spec-generator generate
+routes-api-spec-generator generate --force --root /path/to/rails/app
+routes-api-spec-generator generate --dry-run --namespace /api/v2
+```
+
+### Opções
+
+| Flag | Descrição |
+|------|-----------|
+| `--root PATH` | Raiz do app Rails (default: diretório atual) |
+| `--force` | Sobrescrever specs existentes |
+| `--dry-run` | Listar arquivos sem gravar |
+| `--namespace PATH` | Prefixo de rotas (default: `/api/v1`) |
+
+## Configuração
+
+Opcional: `config/routes_api_spec_generator.yml`
+
+```yaml
+defaults:
+  namespace: /api/v1
+
+endpoints:
+  api/v1/insights#email_metrics:
+    template: insights
+    tag: Insights
+    summary: email origin metrics
+    tenant_header: X-Tenant-ID
+    service_class: Insights::EmailService
+    channel: email
+```
+
+Chaves em `endpoints` seguem `controller#action` (ex.: `api/v1/channels#index`).
+
+## Uso programático
+
+```ruby
+require 'routes_api_spec_generator'
+
+result = RoutesApiSpecGenerator::Generator.new(
+  rails_root: Rails.root,
+  force: false
+).run
+
+puts "Gerados: #{result[:written]}, ignorados: #{result[:skipped]}"
+```
+
+## Publicar no RubyGems.org
+
+```bash
+bundle install
+bundle exec rspec
+gem build routes_api_spec_generator.gemspec
+gem push routes_api_spec_generator-0.1.0.gem
+```
+
+> Requer conta no [RubyGems.org](https://rubygems.org) e MFA habilitado.
+
+## Desenvolvimento
+
+```bash
+git clone https://github.com/saulofilho/routes-api-spec-generator.git
+cd routes-api-spec-generator
+bundle install
+bundle exec rspec
+bundle exec rake
+```
+
+## Fluxo recomendado
+
+```
+routes.rb + controllers  →  routes_api_spec_generator  →  spec/requests/**/*
+                                                              ↓
+                                                         rspec (green)
+                                                              ↓
+                                              rake rswag:specs:swaggerize
+```
+
+## Licença
+
+MIT — veja [LICENSE.txt](LICENSE.txt).

data/exe/routes-api-spec-generator

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'routes_api_spec_generator'
+
+RoutesApiSpecGenerator::CLI.start

data/lib/routes_api_spec_generator/cli.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module RoutesApiSpecGenerator
+  class CLI
+    def self.start(argv = ARGV)
+      new.run(argv)
+    end
+
+    def run(argv)
+      options = {
+        force: false,
+        dry_run: false,
+        namespace: '/api/v1'
+      }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: routes-api-spec-generator generate [options]'
+
+        opts.on('--root PATH', 'Rails app root (default: Dir.pwd)') { |v| options[:root] = v }
+        opts.on('--force', 'Overwrite existing spec files') { options[:force] = true }
+        opts.on('--dry-run', 'Print paths without writing files') { options[:dry_run] = true }
+        opts.on('--namespace PATH', 'Route prefix (default: /api/v1)') { |v| options[:namespace] = v }
+        opts.on('-h', '--help', 'Show help') { puts opts; exit }
+      end
+
+      parser.parse!(argv)
+      command = argv.first || 'generate'
+
+      case command
+      when 'generate'
+        generate!(options)
+      else
+        warn "Unknown command: #{command}"
+        puts parser
+        exit 1
+      end
+    end
+
+    private
+
+      def generate!(options)
+        root = options[:root] || Dir.pwd
+        generator = Generator.new(
+          rails_root: root,
+          force: options[:force],
+          dry_run: options[:dry_run],
+          namespace: options[:namespace]
+        )
+        result = generator.run
+        report(result)
+      end
+
+      def report(result)
+        result[:files].each do |file|
+          case file[:status]
+          when :written
+            puts "✓ wrote #{file[:path]}"
+          when :skipped
+            puts "○ skipped #{file[:path]} (exists; use --force)"
+          when :dry_run
+            puts "→ would write #{file[:path]}"
+          end
+        end
+
+        puts "\nDone: #{result[:written]} written, #{result[:skipped]} skipped, #{result[:dry_run]} dry-run"
+      end
+  end
+end

data/lib/routes_api_spec_generator/config_loader.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RoutesApiSpecGenerator
+  class ConfigLoader
+    DEFAULT_PATH = 'config/routes_api_spec_generator.yml'
+
+    def initialize(rails_root:, config_path: nil)
+      @rails_root = Pathname.new(rails_root)
+      @config_path = config_path || @rails_root.join(DEFAULT_PATH)
+    end
+
+    def load
+      return empty_config unless File.exist?(@config_path)
+
+      YAML.safe_load(File.read(@config_path), aliases: true) || empty_config
+    end
+
+    private
+
+      def empty_config
+        { 'defaults' => {}, 'endpoints' => {} }
+      end
+  end
+end

data/lib/routes_api_spec_generator/controller_inspector.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module RoutesApiSpecGenerator
+  class ControllerInspector
+    SERVICE_PATTERNS = {
+      /metrics_payload\(::Insights::(\w+)\)/ => :insights,
+      /::Channels::ResultsAggregatorService/ => :aggregator,
+      /::Channels::StatsFinder/ => :stats_finder
+    }.freeze
+
+    def initialize(rails_root:)
+      @rails_root = Pathname.new(rails_root)
+    end
+
+    def inspect(controller_path, action)
+      file = controller_file(controller_path)
+      return {} unless file && File.exist?(file)
+
+      source = File.read(file)
+      hints = {
+        permitted_params: extract_permit(source),
+        skip_timezone: source.include?('skip_before_action :validate_timezone'),
+        service_class: extract_service_for_action(source, action),
+        service_pattern: nil
+      }
+
+      hints[:service_pattern] = infer_service_pattern(hints[:service_class], source)
+      hints[:template] = infer_template(controller_path, action, hints, source)
+      hints[:tenant_header] = controller_path.include?('insights') ? 'X-Tenant-ID' : 'Tenant-ID'
+      hints[:channel] = infer_channel(action)
+      hints
+    end
+
+    private
+
+      def controller_file(controller_path)
+        @rails_root.join('app/controllers', "#{controller_path}_controller.rb")
+      end
+
+      def extract_permit(source)
+        match = source.match(/params\.permit\(([^)]+)\)/m)
+        return [] unless match
+
+        match[1].scan(/:(\w+)/).flatten.map(&:to_sym)
+      end
+
+      def extract_service_for_action(source, action)
+        match = source.match(/def #{action}\s*\n.*?metrics_payload\(::Insights::(\w+)\)/m)
+        return "Insights::#{match[1]}" if match
+
+        return 'Channels::ResultsAggregatorService' if source.include?('ResultsAggregatorService')
+        return 'Channels::StatsFinder' if source.include?('StatsFinder')
+
+        nil
+      end
+
+      def infer_service_pattern(service_class, source)
+        return :insights if service_class&.start_with?('Insights::')
+        return :aggregator if service_class == 'Channels::ResultsAggregatorService'
+        return :stats_finder if service_class == 'Channels::StatsFinder' || source.include?('StatsFinder')
+
+        nil
+      end
+
+      def infer_channel(action)
+        return 'email' if action.include?('email')
+        return 'sms' if action.include?('sms')
+        return 'whatsapp' if action.include?('whatsapp')
+
+        nil
+      end
+
+      def infer_template(_controller_path, action, hints, _source)
+        return 'general_metrics' if action == 'general_metrics'
+        return 'insights' if hints[:service_pattern] == :insights
+        return 'big_numbers' if hints[:service_pattern] == :aggregator
+        return 'channels' if hints[:service_pattern] == :stats_finder
+
+        action == 'index' ? 'resource_index' : 'insights'
+      end
+  end
+end

data/lib/routes_api_spec_generator/endpoint.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RoutesApiSpecGenerator
+  Endpoint = Struct.new(
+    :verb,
+    :path,
+    :controller,
+    :action,
+    :template,
+    :tag,
+    :summary,
+    :tenant_header,
+    :service_class,
+    :service_pattern,
+    :spec_filename,
+    :describe_name,
+    :extra_params,
+    :timezone,
+    :channel,
+    :resource_name,
+    keyword_init: true
+  ) do
+    def route_key
+      "#{controller}##{action}"
+    end
+
+    def insights?
+      template == 'insights'
+    end
+
+    def channels?
+      template == 'channels'
+    end
+
+    def big_numbers?
+      template == 'big_numbers'
+    end
+  end
+end

data/lib/routes_api_spec_generator/generator.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module RoutesApiSpecGenerator
+  class Generator
+    OUTPUT_DIR = 'spec/requests'
+
+    def initialize(rails_root:, force: false, dry_run: false, namespace: '/api/v1')
+      @rails_root = Pathname.new(rails_root)
+      @force = force
+      @dry_run = dry_run
+      @namespace = namespace
+      @config = ConfigLoader.new(rails_root: @rails_root).load
+      @inspector = ControllerInspector.new(rails_root: @rails_root)
+    end
+
+    def run
+      require_routes!
+      routes = RouteCollector.new(routes: @routes, namespace_prefix: @namespace).collect
+      endpoints = routes.map { |route| build_endpoint(route) }
+
+      results = endpoints.map { |endpoint| write_endpoint(endpoint) }
+      summary(results)
+    end
+
+    private
+
+      def require_routes!
+        require File.expand_path('config/environment', @rails_root)
+        @routes = Rails.application.routes.routes
+      end
+
+      def build_endpoint(route)
+        route_key = "#{route[:controller]}##{route[:action]}"
+        config = (@config.dig('endpoints', route_key) || {}).transform_keys(&:to_s)
+        hints = @inspector.inspect(route[:controller], route[:action])
+        defaults = (@config['defaults'] || {}).transform_keys(&:to_s)
+
+        template = config['template'] || hints[:template] || 'resource_index'
+        action = route[:action]
+        resource = route[:controller].split('/').last
+
+        spec_filename = config['spec_filename'] || spec_filename_for(resource, action)
+        describe_name = config['describe_name'] || route[:path].delete_prefix('/')
+
+        Endpoint.new(
+          verb: route[:verb],
+          path: route[:path],
+          controller: route[:controller],
+          action: action,
+          template: template,
+          tag: config['tag'] || tag_for(resource, action),
+          summary: config['summary'] || summary_for(resource, action),
+          tenant_header: config['tenant_header'] || hints[:tenant_header] || 'Tenant-ID',
+          service_class: config['service_class'] || hints[:service_class],
+          service_pattern: config['service_pattern'] || hints[:service_pattern]&.to_s,
+          spec_filename: spec_filename,
+          describe_name: describe_name,
+          extra_params: config['extra_params'] || extra_params_for(hints[:permitted_params]),
+          timezone: config.fetch('timezone', !hints[:skip_timezone]),
+          channel: config['channel'] || hints[:channel],
+          resource_name: resource
+        )
+      end
+
+      def spec_filename_for(resource, action)
+        return "#{resource}_spec.rb" if action == 'index'
+
+        "#{action}_spec.rb"
+      end
+
+      def tag_for(resource, action)
+        return resource.singularize.camelize if action == 'index'
+
+        'Insights'
+      end
+
+      def summary_for(resource, action)
+        return "list #{resource.tr('_', ' ')}" if action == 'index'
+
+        "#{action.tr('_', ' ')}"
+      end
+
+      def extra_params_for(permitted)
+        Array(permitted).map(&:to_s) - %w[start_date end_date]
+      end
+
+      def write_endpoint(endpoint)
+        relative = File.join(OUTPUT_DIR, endpoint.path.delete_prefix('/').gsub(%r{/[^/]+$}, '') || '',
+                             endpoint.spec_filename).squeeze('/')
+        # path like /api/v1/channels -> spec/requests/api/v1/channels_spec.rb
+        output = @rails_root.join(OUTPUT_DIR, path_to_spec_dir(endpoint.path), endpoint.spec_filename)
+        content = render(endpoint)
+
+        if File.exist?(output) && !@force
+          return { path: output, status: :skipped }
+        end
+
+        if @dry_run
+          return { path: output, status: :dry_run, content: content }
+        end
+
+        FileUtils.mkdir_p(output.dirname)
+        File.write(output, content)
+        { path: output, status: :written }
+      end
+
+      def path_to_spec_dir(path)
+        # /api/v1/channels -> api/v1
+        # /api/v1/insights/email_metrics -> api/v1
+        segments = path.delete_prefix('/').split('/')
+        segments[0..1].join('/') # api/v1
+      end
+
+      def render(endpoint)
+        template_file = template_path(endpoint.template)
+        context = TemplateContext.new(endpoint)
+        ERB.new(File.read(template_file), trim_mode: '-').result(context.instance_eval { binding })
+      end
+
+      def template_path(name)
+        File.join(__dir__, 'templates', "#{name}.erb")
+      end
+
+      def summary(results)
+        written = results.count { |r| r[:status] == :written }
+        skipped = results.count { |r| r[:status] == :skipped }
+        dry = results.count { |r| r[:status] == :dry_run }
+
+        {
+          written: written,
+          skipped: skipped,
+          dry_run: dry,
+          files: results
+        }
+      end
+  end
+end

data/lib/routes_api_spec_generator/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module RoutesApiSpecGenerator
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load 'routes_api_spec_generator/tasks/routes_api_spec_generator.rake'
+    end
+  end
+end

data/lib/routes_api_spec_generator/route_collector.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RoutesApiSpecGenerator
+  class RouteCollector
+    def initialize(routes:, namespace_prefix: '/api/v1', verbs: %w[GET])
+      @routes = routes
+      @namespace_prefix = namespace_prefix
+      @verbs = verbs.map(&:upcase)
+    end
+
+    def collect
+      @routes.filter_map do |route|
+        next unless matching_route?(route)
+
+        verb = primary_verb(route)
+        next unless @verbs.include?(verb)
+
+        {
+          verb: verb,
+          path: route.path.spec.to_s.gsub('(.:format)', ''),
+          controller: route.defaults[:controller],
+          action: route.defaults[:action].to_s
+        }
+      end.uniq { |r| [r[:path], r[:verb], r[:action]] }
+    end
+
+    private
+
+      def matching_route?(route)
+        path = route.path.spec.to_s
+        return false unless path.start_with?(@namespace_prefix)
+        return false if route.defaults[:controller].blank?
+
+        route.defaults[:controller].exclude?('rails/')
+      end
+
+      def primary_verb(route)
+        verb = route.verb
+        return 'GET' if verb.blank?
+
+        case verb
+        when String
+          verb.upcase
+        when Regexp
+          verb.source.gsub(/[\^\$\(\)]/, '').split('|').first.to_s.upcase
+        else
+          'GET'
+        end
+      end
+  end
+end

data/lib/routes_api_spec_generator/tasks/routes_api_spec_generator.rake

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'routes_api_spec_generator'
+require 'rake'
+
+namespace :routes_api_spec do
+  desc 'Generate rswag request specs from Rails routes'
+  task generate: :environment do
+    result = RoutesApiSpecGenerator::Generator.new(
+      rails_root: Rails.root,
+      force: ENV['FORCE'] == 'true',
+      dry_run: ENV['DRY_RUN'] == 'true'
+    ).run
+
+    result[:files].each do |file|
+      case file[:status]
+      when :written then puts "✓ #{file[:path]}"
+      when :skipped then puts "○ #{file[:path]}"
+      when :dry_run then puts "→ #{file[:path]}"
+      end
+    end
+
+    puts "Done: #{result[:written]} written, #{result[:skipped]} skipped"
+  end
+end

data/lib/routes_api_spec_generator/template_context.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RoutesApiSpecGenerator
+  class TemplateContext
+    attr_reader :endpoint
+
+    def initialize(endpoint)
+      @endpoint = endpoint
+    end
+  end
+end

data/lib/routes_api_spec_generator/templates/big_numbers.erb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+require 'swagger_helper'
+
+RSpec.describe '<%= endpoint.describe_name %>', type: :request do
+  let(:'<%= endpoint.tenant_header %>') { '176980161229322768' }
+  let(:start_date) { '2026-03-01' }
+  let(:end_date) { '2026-03-31' }
+<% if endpoint.extra_params.include?('period') -%>
+  let(:period) { 'custom' }
+<% end -%>
+
+  path '<%= endpoint.path %>' do
+    get('<%= endpoint.summary %>') do
+      tags '<%= endpoint.tag %>'
+      produces 'application/json'
+
+      parameter name: '<%= endpoint.tenant_header %>', in: :header, schema: { type: :string }, required: true
+      parameter name: :start_date, in: :query, schema: { type: :string, format: :date }, required: true
+      parameter name: :end_date, in: :query, schema: { type: :string, format: :date }, required: true
+<% endpoint.extra_params.each do |param| -%>
+      parameter name: :<%= param %>, in: :query, schema: { type: :string }, required: false
+<% end -%>
+
+      response(200, 'successful') do
+        schema type: :object
+
+        let(:aggregator) { instance_double(Channels::ResultsAggregatorService) }
+
+        before do
+          allow(Channels::ResultsAggregatorService).to receive(:new).and_return(aggregator)
+          allow(aggregator).to receive(:call).and_return([])
+        end
+
+        run_test!
+      end
+
+      response(400, 'bad request - invalid dates') do
+        let(:start_date) { 'data-invalida' }
+        run_test!
+      end
+
+      response(400, 'bad request - missing tenant') do
+        let(:'<%= endpoint.tenant_header %>') { nil }
+        run_test!
+      end
+    end
+  end
+end

data/lib/routes_api_spec_generator/templates/channels.erb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+require 'swagger_helper'
+
+RSpec.describe '<%= endpoint.describe_name %>', type: :request do
+  let(:'<%= endpoint.tenant_header %>') { 'test-tenant' }
+<% if endpoint.timezone -%>
+  let(:Timezone) { 'UTC' }
+<% end -%>
+  let(:start_date) { '2026-01-01' }
+  let(:end_date) { '2026-01-31' }
+
+  path '<%= endpoint.path %>' do
+    get('<%= endpoint.summary %>') do
+      tags '<%= endpoint.tag %>'
+      produces 'application/json'
+
+      parameter name: '<%= endpoint.tenant_header %>', in: :header, schema: { type: :string }, required: true
+<% if endpoint.timezone -%>
+      parameter name: 'Timezone', in: :header, schema: { type: :string }, required: false
+<% end -%>
+      parameter name: :start_date, in: :query, schema: { type: :string, format: :date }, required: true
+      parameter name: :end_date, in: :query, schema: { type: :string, format: :date }, required: true
+
+      response(200, 'successful') do
+        schema type: :object
+
+        before do
+          allow_any_instance_of(Channels::EmailService).to receive(:fetch_stats)
+            .and_return({ channel: 'email', sent: 100, delivered: 90, clicked: 10 })
+          allow_any_instance_of(Channels::WhatsappService).to receive(:fetch_stats)
+            .and_return({ channel: 'whatsapp', sent: 50, delivered: 45, clicked: nil })
+          allow_any_instance_of(Channels::SmsService).to receive(:fetch_stats)
+            .and_return({ channel: 'sms', sent: 30, delivered: 25, clicked: 5 })
+        end
+
+        run_test!
+      end
+
+      response(400, 'bad request - missing dates') do
+        let(:start_date) { nil }
+        let(:end_date) { nil }
+        run_test!
+      end
+
+      response(400, 'bad request - missing tenant') do
+        let(:'<%= endpoint.tenant_header %>') { nil }
+        run_test!
+      end
+    end
+  end
+end

data/lib/routes_api_spec_generator/templates/general_metrics.erb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+require 'swagger_helper'
+
+RSpec.describe '<%= endpoint.describe_name %>', type: :request do
+  let(:'<%= endpoint.tenant_header %>') { '176980161229322768' }
+  let(:start_date) { '2026-03-01' }
+  let(:end_date) { '2026-03-31' }
+
+  path '<%= endpoint.path %>' do
+    get('<%= endpoint.summary %>') do
+      tags '<%= endpoint.tag %>'
+      produces 'application/json'
+
+      parameter name: '<%= endpoint.tenant_header %>', in: :header, schema: { type: :string }, required: true
+      parameter name: :start_date, in: :query, schema: { type: :string, format: :date }, required: true
+      parameter name: :end_date, in: :query, schema: { type: :string, format: :date }, required: true
+
+      response(200, 'successful') do
+        schema type: :object, required: ['data']
+
+        let(:service) { instance_double(<%= endpoint.service_class %>) }
+
+        before do
+          allow(<%= endpoint.service_class %>).to receive(:new)
+            .with('176980161229322768', period: { start_date: start_date, end_date: end_date })
+            .and_return(service)
+          allow(service).to receive(:call).and_return(
+            data: {
+              period: { start_date: start_date, end_date: end_date },
+              result: [
+                { channel: 'email', total_sent: 100, total_delivered: 90 }
+              ]
+            }
+          )
+        end
+
+        run_test!
+      end
+
+      response(400, 'bad request - invalid dates') do
+        let(:start_date) { 'data-invalida' }
+        run_test!
+      end
+
+      response(400, 'bad request - missing tenant') do
+        let(:'<%= endpoint.tenant_header %>') { nil }
+        run_test!
+      end
+    end
+  end
+end

data/lib/routes_api_spec_generator/templates/insights.erb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+require 'swagger_helper'
+
+RSpec.describe '<%= endpoint.describe_name %>', type: :request do
+  let(:'<%= endpoint.tenant_header %>') { '176980161229322768' }
+  let(:start_date) { '2026-03-01' }
+  let(:end_date) { '2026-03-31' }
+
+  path '<%= endpoint.path %>' do
+    get('<%= endpoint.summary %>') do
+      tags '<%= endpoint.tag %>'
+      produces 'application/json'
+
+      parameter name: '<%= endpoint.tenant_header %>', in: :header, schema: { type: :string }, required: true
+      parameter name: :start_date, in: :query, schema: { type: :string, format: :date }, required: true
+      parameter name: :end_date, in: :query, schema: { type: :string, format: :date }, required: true
+
+      response(200, 'successful') do
+        schema type: :object, required: ['data']
+
+        let(:service) { instance_double(<%= endpoint.service_class %>) }
+
+        before do
+          allow(<%= endpoint.service_class %>).to receive(:new)
+            .with('176980161229322768', period: { start_date: start_date, end_date: end_date })
+            .and_return(service)
+          allow(service).to receive(:call).and_return(
+            data: {
+              period: { start_date: start_date, end_date: end_date },
+<% if endpoint.channel -%>
+              channel: '<%= endpoint.channel %>',
+<% end -%>
+              result: []
+            }
+          )
+        end
+
+        run_test!
+      end
+
+      response(400, 'bad request - invalid dates') do
+        let(:start_date) { 'data-invalida' }
+        run_test!
+      end
+
+      response(400, 'bad request - missing tenant') do
+        let(:'<%= endpoint.tenant_header %>') { nil }
+        run_test!
+      end
+    end
+  end
+end

data/lib/routes_api_spec_generator/templates/resource_index.erb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+require 'swagger_helper'
+
+RSpec.describe '<%= endpoint.describe_name %>', type: :request do
+  let(:'<%= endpoint.tenant_header %>') { '176980161229322768' }
+  let(:start_date) { '2026-03-01' }
+  let(:end_date) { '2026-03-31' }
+
+  path '<%= endpoint.path %>' do
+    get('<%= endpoint.summary %>') do
+      tags '<%= endpoint.tag %>'
+      produces 'application/json'
+
+      parameter name: '<%= endpoint.tenant_header %>', in: :header, schema: { type: :string }, required: true
+      parameter name: :start_date, in: :query, schema: { type: :string, format: :date }, required: true
+      parameter name: :end_date, in: :query, schema: { type: :string, format: :date }, required: true
+
+      response(200, 'successful') do
+        schema type: :object
+
+        run_test!
+      end
+
+      response(400, 'bad request - invalid dates') do
+        let(:start_date) { 'data-invalida' }
+        run_test!
+      end
+
+      response(400, 'bad request - missing tenant') do
+        let(:'<%= endpoint.tenant_header %>') { nil }
+        run_test!
+      end
+    end
+  end
+end

data/lib/routes_api_spec_generator/version.rb

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

data/lib/routes_api_spec_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/string/inflections'
+require 'erb'
+require 'yaml'
+
+require_relative 'routes_api_spec_generator/version'
+require_relative 'routes_api_spec_generator/endpoint'
+require_relative 'routes_api_spec_generator/config_loader'
+require_relative 'routes_api_spec_generator/route_collector'
+require_relative 'routes_api_spec_generator/controller_inspector'
+require_relative 'routes_api_spec_generator/generator'
+require_relative 'routes_api_spec_generator/template_context'
+require_relative 'routes_api_spec_generator/cli'
+
+require_relative 'routes_api_spec_generator/railtie' if defined?(Rails::Railtie)
+
+module RoutesApiSpecGenerator
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: routes_api_spec_generator
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Saulo Filho
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: |
+  Ruby gem que lê rotas e controllers de uma API Rails e materializa
+  request specs RSpec com rswag — alinhado ao fluxo spec → swagger
+  (rswag:specs:swaggerize).
+email:
+- saulofilho@users.noreply.github.com
+executables:
+- routes-api-spec-generator
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/routes-api-spec-generator
+- lib/routes_api_spec_generator.rb
+- lib/routes_api_spec_generator/cli.rb
+- lib/routes_api_spec_generator/config_loader.rb
+- lib/routes_api_spec_generator/controller_inspector.rb
+- lib/routes_api_spec_generator/endpoint.rb
+- lib/routes_api_spec_generator/generator.rb
+- lib/routes_api_spec_generator/railtie.rb
+- lib/routes_api_spec_generator/route_collector.rb
+- lib/routes_api_spec_generator/tasks/routes_api_spec_generator.rake
+- lib/routes_api_spec_generator/template_context.rb
+- lib/routes_api_spec_generator/templates/big_numbers.erb
+- lib/routes_api_spec_generator/templates/channels.erb
+- lib/routes_api_spec_generator/templates/general_metrics.erb
+- lib/routes_api_spec_generator/templates/insights.erb
+- lib/routes_api_spec_generator/templates/resource_index.erb
+- lib/routes_api_spec_generator/version.rb
+homepage: https://github.com/saulofilho/routes-api-spec-generator
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/saulofilho/routes-api-spec-generator
+  source_code_uri: https://github.com/saulofilho/routes-api-spec-generator
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: Gera request specs rswag a partir de rotas Rails
+test_files: []