swagger_docs_rails 0.1.0

data/lib/swagger_docs_rails/controller_parser.rb

@@ -0,0 +1,556 @@
+# frozen_string_literal: true
+# lib/swagger_docs_rails/controller_parser.rb
+#
+# Escaneia app/controllers/api/**/*.rb e extrai por controller:
+#
+#  Ações CRUD padrão (index, show, create, update, destroy)
+#  Ações customizadas (importar, upload_arquivo, etc.)
+#  params.permit por ação — direto no corpo ou via método privado referenciado
+#  Campos de arquivo (format: binary) detectados pelo nome e pelo corpo da ação
+#  Detecção de multipart/form-data (Roo::, .original_filename, params[:arquivo], etc.)
+#  Padrão Model.column_names.reject{}.permit(*permitted, :extra_field)
+#  Método HTTP de ações customizadas (heurística por nome + @swagger_method_X)
+#  Metadados de documentação via comentários @swagger_*
+#  Estruturas aninhadas recursivas (ex: responsaveis: [ { nome:, enderecos: [] } ])
+
+module SwaggerDocsRails
+  class ControllerParser
+    CRUD_ACTIONS = %w[index show create update destroy].freeze
+
+    # Heurística nome → HTTP para ações customizadas
+    CUSTOM_HTTP_HINTS = {
+      /\A(import|importar|upload|enviar|processar|executar|sincronizar|
+          gerar|calcular|acionar|criar|cadastrar)/x => :post,
+      /\A(download|exportar|relatorio|report|preview|visualizar|listar|buscar)/x => :get,
+      /\A(ativar|desativar|aprovar|rejeitar|cancelar|bloquear|
+          desbloquear|definir|remover|atualizar|alterar)/x => :patch,
+      /\Adelete_/ => :delete
+    }.freeze
+
+    # Tipo OpenAPI pelo nome do campo
+    FIELD_TYPE_MAP = {
+      /_id\z/                                          => { type: "integer", format: "int64" },
+      /\Aemail|_email\z/                               => { type: "string",  format: "email" },
+      /password|senha/                                 => { type: "string",  format: "password" },
+      /\Acpf\z|\Acnpj\z|cpf_cnpj/                      => { type: "string" },
+      /\Adata_|\A.*_at\z|data_nascimento/              => { type: "string",  format: "date" },
+      /valor|preco|percentual|taxa/                    => { type: "number",  format: "double" },
+      /\Aativo\z|proprio|embutido|possui|admin|bloqueado/ => { type: "boolean" },
+      /nivel|numero|tentativas/                        => { type: "integer" }
+    }.freeze
+
+    # Indicadores de upload no corpo de uma ação ou nos seus params privados
+    MULTIPART_INDICATORS = [
+      /\.original_filename\b/,
+      /\.content_type\b/,
+      /\.read\b/,
+      /Roo::/,
+      /ActionDispatch.*UploadedFile/,
+      /CarrierWave|Shrine|ActiveStorage\.attach/,
+      /params\[:arquivo\]/,
+      /params\[:file\]/,
+      /params\[:anexo\]/,
+      /params\[:imagem\]/,
+      /params\[:foto\]/,
+      /\.tempfile\b/
+    ].freeze
+
+    # Padrões de campo de arquivo pelo nome (excluindo _url)
+    FILE_FIELD_PATTERN = /
+      \Aimagem_|\Afoto_|\Aanexo_|\Adocumento_|\Aplanilha_|  # prefixo
+      _imagem\z|_foto\z|_anexo\z|_arquivo\z|               # sufixo
+      \Aarquivo\z|\Afile\z|_file\z|                         # exatos
+      \Aanexo\z|\Aimagem\z|\Afoto\z|                        # exatos pt-br
+      \Alogo\z|\Aavatar\z|\Athumbnail\z|\Acover\z|          # imagens comuns
+      \Adocumento\z|\Aplanilha\z|\Arelatorio\z              # docs
+    /x.freeze
+
+    attr_reader :controllers
+
+    def initialize(paths = nil)
+      @search_paths = Array(paths || [Rails.root.join("app", "controllers", "api")])
+      @controllers  = []
+      @routes_map   = parse_routes_file!
+      parse!
+    end
+
+    def to_resources
+      @controllers
+    end
+
+    def self.infer_field_type(field_name)
+      FIELD_TYPE_MAP.each do |pattern, type_def|
+        return type_def.dup if field_name.to_s.match?(pattern)
+      end
+      { type: "string" }
+    end
+
+    private
+
+    # ─────────────────────────────────────────────────────── parse ──
+
+    def parse!
+      @search_paths.each do |base|
+        Dir.glob(File.join(base.to_s, "**", "*.rb")).sort.each do |file|
+          info = extract_info(file, File.read(file))
+          @controllers << info if info
+        end
+      end
+    end
+
+    def extract_info(file, content)
+      klass_match = content.match(/class\s+([\w:]+Controller)/)
+      return nil unless klass_match
+
+      klass = klass_match[1]
+      return nil unless klass.start_with?("Api::")
+
+      version       = extract_version(klass)
+      resource_name = File.basename(file, ".rb").sub(/_controller$/, "")
+      model_name    = infer_model_name(resource_name)
+
+      public_body, private_body = split_public_private(content)
+      public_actions = scan_public_actions(public_body)
+      return nil if public_actions.empty?
+
+      unauthenticated_actions = extract_unauthenticated_actions(content)
+      private_permit_map = extract_private_permit_methods(private_body)
+      actions_meta       = build_actions_meta(public_actions, public_body, private_permit_map,
+                                              unauthenticated_actions)
+
+      crud   = public_actions & CRUD_ACTIONS
+      custom = public_actions - CRUD_ACTIONS
+
+      {
+        controller_class:       klass,
+        resource:               resource_name,
+        model:                  model_name,
+        version:                version,
+        actions:                crud,
+        custom_actions:         build_custom_actions(custom, content, actions_meta),
+        actions_meta:           actions_meta,
+        unauthenticated_actions: unauthenticated_actions,
+        extra_meta:             extract_swagger_meta(content)
+      }
+    end
+
+    def split_public_private(content)
+      idx = content.index(/^\s+private\b/)
+      idx ? [content[0...idx], content[idx..]] : [content, ""]
+    end
+
+    def scan_public_actions(body)
+      body.scan(/^\s+def\s+(\w+)\b/).flatten.uniq
+    end
+
+    def extract_private_permit_methods(private_body)
+      result = {}
+      private_body.scan(/def\s+(\w+)(.*?)(?=\n\s+def\s|\z)/m) do |mname, mbody|
+        meta = extract_permit_meta(mbody)
+        result[mname] = meta if meta[:fields].any? || meta[:uses_column_names] || meta[:nested_arrays].any?
+      end
+      result
+    end
+
+    def extract_permit_meta(body)
+      structure = extract_permit_fields(body)
+      uses_column_names = body.match?(/\.column_names\b/)
+      model_name = nil
+      extra_fields = []
+
+      if uses_column_names
+        m = body.match(/(\w+)\.column_names/)
+        model_name = m[1] if m
+        extra_fields = extract_extra_fields_after_splat(body)
+        structure[:scalar_fields] = (structure[:scalar_fields] | extra_fields)
+      end
+
+      file_fields = detect_file_fields_by_name(structure[:scalar_fields]) | detect_file_fields_by_access(body)
+
+      {
+        fields:             structure[:scalar_fields],
+        array_fields:       structure[:array_fields],
+        nested_arrays:      structure[:nested_arrays],
+        file_fields:        file_fields,
+        extra_fields:       extra_fields,
+        uses_column_names:  uses_column_names,
+        column_names_model: model_name
+      }
+    end
+
+    def extract_extra_fields_after_splat(body)
+      extras = []
+      body.scan(/\.permit\((?:[^)]*\*\w+[^,)]*),\s*(.*?)\)/m) do |after|
+        after.first.to_s.scan(/[:"'](\w+)["']?/).flatten.each { |f| extras << f unless f.empty? }
+      end
+      extras.uniq
+    end
+
+    def build_actions_meta(actions, public_body, private_permit_map, unauthenticated_actions = [])
+      meta = {}
+      actions.each do |action|
+        body = extract_action_body(action, public_body)
+        next unless body
+
+        permit_meta     = resolve_permit_meta(body, private_permit_map)
+        body_multipart  = detect_multipart(body)
+        all_file_fields = (permit_meta[:file_fields] + detect_file_fields_by_access(body)).uniq
+
+        permit_has_file = permit_meta[:fields].any? { |f| file_field_by_name?(f) }
+        is_multipart    = body_multipart || all_file_fields.any? || permit_has_file
+
+        if permit_has_file
+          permit_files = permit_meta[:fields].select { |f| file_field_by_name?(f) }
+          all_file_fields = (all_file_fields + permit_files).uniq
+        end
+
+        meta[action] = {
+          permit_fields:      permit_meta[:fields],
+          array_fields:       permit_meta[:array_fields] || [],
+          nested_arrays:      permit_meta[:nested_arrays] || {},
+          file_fields:        all_file_fields,
+          extra_fields:       permit_meta[:extra_fields] || [],
+          uses_column_names:  permit_meta[:uses_column_names],
+          column_names_model: permit_meta[:column_names_model],
+          grouped_params:     permit_meta[:grouped_params],
+          is_multipart:       is_multipart,
+          http_method:        crud_http_method(action),
+          uses_service:       body.match?(/Service\.new|\.call\b/),
+          unauthenticated:    unauthenticated_actions.include?(action)
+        }
+      end
+      meta
+    end
+
+    def extract_action_body(action, content)
+      m = content.match(/def\s+#{Regexp.escape(action)}\b(.*?)(?=\n\s+def\s|\z)/m)
+      m ? m[1] : nil
+    end
+
+    def resolve_permit_meta(action_body, private_permit_map)
+      inline = extract_permit_meta(action_body)
+      if inline[:fields].any? || inline[:array_fields].any? || inline[:nested_arrays].any?
+        return inline
+      end
+
+      called  = action_body.scan(/\b(\w+_params?\b|\w+_permit\w*)\b/).flatten.uniq
+      matched = called.filter_map { |m| [m, private_permit_map[m]] if private_permit_map[m] }
+
+      return empty_permit_meta if matched.empty?
+
+      if matched.size == 1
+        return matched.first[1].merge(grouped_params: nil)
+      end
+
+      groups = matched.map do |method_name, meta|
+        group_key = method_name.sub(/_params?\z/, "").sub(/\Aparams_/, "")
+        { key: group_key, meta: meta }
+      end
+
+      {
+        fields:             [],
+        array_fields:       [],
+        nested_arrays:      {},
+        file_fields:        [],
+        extra_fields:       [],
+        uses_column_names:  false,
+        column_names_model: nil,
+        grouped_params:     groups
+      }
+    end
+
+    def empty_permit_meta
+      { fields: [], array_fields: [], nested_arrays: {}, file_fields: [], extra_fields: [],
+        uses_column_names: false, column_names_model: nil, grouped_params: nil }
+    end
+
+    def extract_permit_fields(text)
+      result = { scalar_fields: [], array_fields: [], nested_arrays: {} }
+
+      normalized = text.gsub(/\n/, ' ').gsub(/\s+/, ' ')
+
+      normalized.scan(/params(?:\[[\w:"' ]+\])?\.(?:require\([\w:"']+\)\.)?permit\((.*?)\)/m) do |args|
+        parsed = parse_permit_args_recursive(args.first.to_s)
+        merge_permit_result(result, parsed)
+      end
+
+      normalized.scan(/params\.expect\(\s*\w+:\s*\[(.*?)\]\s*\)/m) do |args|
+        parsed = parse_permit_args_recursive(args.first.to_s)
+        merge_permit_result(result, parsed)
+      end
+
+      normalized.scan(/\b(\w+)\.permit\((.*?)\)/m) do |var, args|
+        next if var == "params"
+        if text.match?(/\b#{Regexp.escape(var)}\s*=.*\bparams\b/m)
+          parsed = parse_permit_args_recursive(args)
+          merge_permit_result(result, parsed)
+        end
+      end
+
+      result
+    end
+
+    def merge_permit_result(target, source)
+      target[:scalar_fields] |= source[:scalar_fields]
+      target[:array_fields]  |= source[:array_fields]
+      source[:nested_arrays].each do |k, v|
+        target[:nested_arrays][k] ||= { scalar_fields: [], array_fields: [], nested_arrays: {} }
+        merge_permit_result(target[:nested_arrays][k], v)
+      end
+    end
+
+    def parse_permit_args_recursive(args_str)
+      result = { scalar_fields: [], array_fields: [], nested_arrays: {} }
+      return result if args_str.strip.empty?
+
+      tokens = tokenize_permit_args(args_str)
+      tokens.each do |token|
+        token = token.strip
+        next if token.empty?
+
+        if token.include?(':') && !token.start_with?(':')
+          key, value = token.split(':', 2)
+          key = clean_symbol(key)
+          value = value.strip
+
+          if value.start_with?('[') && value.end_with?(']')
+            inner = value[1..-2]
+            if inner.include?(':') && !inner.match(/^:\w+$/)
+              result[:nested_arrays][key] = parse_permit_args_recursive(inner)
+            else
+              result[:array_fields] << key
+            end
+          elsif value.start_with?('{') && value.end_with?('}')
+            inner = value[1..-2]
+            result[:nested_arrays][key] = parse_permit_args_recursive(inner)
+          else
+            result[:scalar_fields] << key
+          end
+        else
+          field = clean_symbol(token)
+          result[:scalar_fields] << field unless field.empty?
+        end
+      end
+
+      result
+    end
+
+    def clean_symbol(str)
+      str.to_s.strip.gsub(/\A[:"]|["]\z/, '')
+    end
+
+    def tokenize_permit_args(str)
+      tokens = []
+      current = +''
+      depth = 0
+      in_string = false
+
+      str.each_char do |ch|
+        case ch
+        when '[', '{', '('
+          depth += 1
+          current << ch
+        when ']', '}', ')'
+          depth -= 1
+          current << ch
+        when ','
+          if depth == 0 && !in_string
+            tokens << current
+            current = +''
+          else
+            current << ch
+          end
+        when '"', "'"
+          in_string = !in_string
+          current << ch
+        else
+          current << ch
+        end
+      end
+      tokens << current unless current.empty?
+      tokens.map(&:strip)
+    end
+
+    def build_custom_actions(action_names, full_content, actions_meta)
+      action_names.map do |name|
+        ameta           = actions_meta[name] || {}
+        all_file_fields = ameta[:file_fields] || []
+        {
+          name:               name,
+          http_method:        infer_custom_http_method(name, full_content),
+          on_member:          infer_on_member(name, full_content),
+          extra_path_params:  extra_path_params_for(name),
+          permit_fields:      ameta[:permit_fields]      || [],
+          array_fields:       ameta[:array_fields]       || [],
+          nested_arrays:      ameta[:nested_arrays]      || {},
+          file_fields:        all_file_fields,
+          extra_fields:       ameta[:extra_fields]       || [],
+          grouped_params:     ameta[:grouped_params],
+          uses_service:       ameta[:uses_service]       || false,
+          is_multipart:       ameta[:is_multipart]       || all_file_fields.any?,
+          uses_column_names:  ameta[:uses_column_names]  || false,
+          column_names_model: ameta[:column_names_model],
+          unauthenticated:    ameta[:unauthenticated]    || false
+        }
+      end
+    end
+
+    def infer_custom_http_method(action_name, content)
+      comment = content.match(/#\s*@swagger_method_#{action_name}:\s*(\w+)/i)
+      return comment[1].downcase.to_sym if comment
+
+      if @routes_map.key?(action_name.to_s)
+        entry = @routes_map[action_name.to_s]
+        return entry.is_a?(Hash) ? entry[:method] : entry
+      end
+
+      CUSTOM_HTTP_HINTS.each { |pattern, method| return method if action_name.match?(pattern) }
+      :post
+    end
+
+    def extra_path_params_for(action_name)
+      entry = @routes_map[action_name.to_s]
+      return [] unless entry.is_a?(Hash)
+      entry[:path_params] || []
+    end
+
+    def infer_on_member(action_name, full_content)
+      routes_path = Rails.root.join("config", "routes.rb")
+      return false unless File.exist?(routes_path)
+
+      routes_content = File.read(routes_path)
+
+      return false if routes_content.match?(/\b(get|post|put|patch|delete)\s+['":][^'"\n]*\b#{Regexp.escape(action_name)}\b[^'"\n]*['"]?[^\n]*on:\s*:collection/i)
+      return false if inside_block?(routes_content, "collection", action_name)
+      return true if routes_content.match?(/\b(get|post|put|patch|delete)\s+['":][^'"\n]*\b#{Regexp.escape(action_name)}\b[^'"\n]*['"]?[^\n]*on:\s*:member/i)
+      return true if inside_block?(routes_content, "member", action_name)
+
+      false
+    end
+
+    def inside_block?(content, block_type, action_name)
+      lines = content.lines
+      lines.each_with_index do |line, idx|
+        next unless line.match?(/\b#{block_type}\s+do\b/)
+
+        depth = 1
+        block_lines = []
+        lines[(idx + 1)..].each do |inner_line|
+          depth += inner_line.scan(/\bdo\b|\bbegin\b/).size
+          depth -= inner_line.scan(/\bend\b/).size
+          break if depth <= 0
+          block_lines << inner_line
+        end
+
+        block_text = block_lines.join
+        return true if block_text.match?(/\b(get|post|put|patch|delete)\s+:#{Regexp.escape(action_name)}\b/) ||
+                       block_text.match?(/\b(get|post|put|patch|delete)\s+['"][^'"]*#{Regexp.escape(action_name)}[^'"]*['"]/) ||
+                       block_text.match?(/action:\s*:#{Regexp.escape(action_name)}\b/)
+      end
+      false
+    end
+
+    def extract_unauthenticated_actions(content)
+      actions = []
+      content.scan(/skip_before_action\s+:(?:authenticate\w*)\s*(?:,\s*only:\s*[\[%]i?\[?(.*?)\]?\s*\n)/m) do |match|
+        match.first.to_s.scan(/[:"'](\w+)["']?/).flatten.each { |a| actions << a }
+      end
+      content.scan(/skip_before_action\s+[:'"]\w+['"]?\s*,\s*only:\s*[\[%]i?\[?([^\]]+)\]?/m) do |match|
+        match.first.to_s.scan(/[:"'](\w+)["']?/).flatten.each { |a| actions << a }
+      end
+      actions.uniq
+    end
+
+    def detect_multipart(body)
+      MULTIPART_INDICATORS.any? { |p| body.match?(p) }
+    end
+
+    def detect_file_fields_by_name(fields)
+      fields.select { |f| file_field_by_name?(f) }
+    end
+
+    def detect_file_fields_by_access(body)
+      fields = []
+      body.scan(/params\[:(\w+)\]/).flatten.each do |f|
+        fields << f if f.match?(/arquivo|file|planilha|documento|imagem|foto|anexo/)
+      end
+      body.scan(/params\[:(\w+)\][^\n]*(?:\.original_filename|\.read|\.content_type)/).flatten.each do |f|
+        fields << f
+      end
+      fields.uniq
+    end
+
+    def file_field_by_name?(name)
+      n = name.to_s
+      return false if n.end_with?("_url") || n.end_with?("url")
+      n.match?(FILE_FIELD_PATTERN)
+    end
+
+    def parse_routes_file!
+      routes_path = Rails.root.join("config", "routes.rb")
+      return {} unless File.exist?(routes_path)
+
+      content = File.read(routes_path)
+      routes_map = {}
+
+      content.scan(/\b(get|post|put|patch|delete)\s+:(\w+)/) do |method, action|
+        next if CRUD_ACTIONS.include?(action)
+        routes_map[action] ||= { method: method.downcase.to_sym, path_params: [] }
+      end
+
+      content.scan(/\b(get|post|put|patch|delete)\s+['"]([^'"]+)['"]\s*,\s*action:\s*:(\w+)/) do |method, path, action|
+        next if CRUD_ACTIONS.include?(action)
+        path_params = path.scan(/:(\w+)/).flatten
+        routes_map[action] ||= { method: method.downcase.to_sym, path_params: path_params }
+      end
+
+      content.scan(/\b(get|post|put|patch|delete)\s+['"]([^'"]+)['"]\s*,\s*to:\s*['"][^'"#]*#(\w+)['"]/) do |method, path, action|
+        next if CRUD_ACTIONS.include?(action)
+        path_params = path.scan(/:(\w+)/).flatten
+        routes_map[action] ||= { method: method.downcase.to_sym, path_params: path_params }
+      end
+
+      content.scan(/\b(get|post|put|patch|delete)\s+['"]([^'"]+)['"]\s*(?!,)/) do |method, path|
+        action = path.split("/").last.to_s.gsub(/:.*/, "").gsub(/[^a-z_]/, "")
+        next if action.empty? || CRUD_ACTIONS.include?(action)
+        path_params = path.scan(/:(\w+)/).flatten
+        routes_map[action] ||= { method: method.downcase.to_sym, path_params: path_params }
+      end
+
+      routes_map
+    end
+
+    def extract_version(klass)
+      m = klass.match(/::V(\d+)::/)
+      m ? "v#{m[1]}" : "v1"
+    end
+
+    def infer_model_name(resource_name)
+      singular = resource_name.singularize rescue resource_name.sub(/s$/, "")
+      parts    = singular.split("_")
+      parts.first == "g" ? "G" + parts[1..].map(&:capitalize).join : parts.map(&:capitalize).join
+    end
+
+    def crud_http_method(action)
+      { "index" => :get, "show" => :get, "create" => :post,
+        "update" => :patch, "destroy" => :delete }.fetch(action, :get)
+    end
+
+    def extract_swagger_meta(content)
+      meta = {}
+      tag_m = content.match(/#\s*@swagger_tag:\s*(.+)/)
+      meta[:tag] = tag_m[1].strip if tag_m
+
+      content.scan(/#\s*@swagger_summary_(\w+):\s*(.+)/).each    { |a, v| meta[:"summary_#{a}"]     = v.strip }
+      content.scan(/#\s*@swagger_description_(\w+):\s*(.+)/).each { |a, v| meta[:"description_#{a}"] = v.strip }
+      content.scan(/#\s*@swagger_params_(\w+):\s*(.+)/).each do |action, fields_str|
+        meta[:"params_#{action}"] = fields_str.strip.split(/\s*,\s*/).map(&:strip)
+      end
+      content.scan(/#\s*@swagger_response_(\w+):\s*(.+)/).each do |action, fields_str|
+        meta[:"response_#{action}"] = fields_str.strip.split(/\s*,\s*/).map(&:strip)
+      end
+
+      meta
+    end
+  end
+end

data/lib/swagger_docs_rails/engine.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "rails"
+require "action_controller/railtie"
+
+module SwaggerDocsRails
+  class Engine < ::Rails::Engine
+    isolate_namespace SwaggerDocsRails
+
+    rake_tasks do
+      load File.expand_path("../tasks/swagger_docs_rails.rake", __dir__)
+    end
+  end
+end

data/lib/swagger_docs_rails/generator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+# lib/swagger_docs_rails/generator.rb
+
+module SwaggerDocsRails
+  class Generator
+    def initialize(opts = {})
+      @schema_path      = opts[:schema_path]
+      @controllers_path = opts[:controllers_path]
+      @config           = opts.fetch(:config, {})
+    end
+
+    def generate
+      schema_parser     = SchemaParser.new(@schema_path)
+      controller_parser = ControllerParser.new(controller_paths)
+      OpenapiBuilder.new(schema_parser, controller_parser, @config).build
+    end
+
+    def generate_json
+      JSON.pretty_generate(generate)
+    end
+
+    def write(output_path = nil)
+      output_path ||= SwaggerDocsRails.configuration.output_path
+      FileUtils.mkdir_p(File.dirname(output_path.to_s))
+      File.write(output_path.to_s, JSON.pretty_generate(generate))
+      output_path
+    end
+
+    private
+
+    def controller_paths
+      return @controllers_path if @controllers_path
+
+      [
+        Rails.root.join("app", "controllers", "api"),
+        *Array(SwaggerDocsRails.configuration.additional_controller_paths)
+      ]
+    end
+  end
+end