rails_map 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4df0308c2e2f34c47e8b9979ee52effe81267e74e2ac4dbaf626e830791f239f
+  data.tar.gz: '0306782d5ef8379eeb5699c53903df2bf9f1b08f24e5e55bd84770bf9302ef7c'
+SHA512:
+  metadata.gz: fb076b72fb3b392e0c772dd089ffe5c12f2c0846a88cddaa933d15d7bc629ad6df383378eb5a74cd01c740bc71ae8c4d24ba2fbd6a49688d0aae7b1efba8fb05
+  data.tar.gz: 92a0a50c1ef9739ce4220c351dc01af2e2d8e38af041b8041f56ae63eb8c45ef336b7f6aee1ffee47b10ac8c6472b4681a19f3b89a30e48a2cac81253b48c5e9

data/.idea/.gitignore

@@ -0,0 +1,8 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

data/.idea/material_theme_project_new.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="MaterialThemeProjectNewConfig">
+    <option name="metadata">
+      <MTProjectMetadataState>
+        <option name="migrated" value="true" />
+        <option name="pristineConfig" value="false" />
+        <option name="userId" value="62b859e4:1995d57850e:-7ff9" />
+      </MTProjectMetadataState>
+    </option>
+  </component>
+</project>

data/AUTHENTICATION.md

@@ -0,0 +1,221 @@
+# Authentication Setup Guide
+
+This guide shows you how to protect your Rails documentation with authentication.
+
+## Setup Steps
+
+### 1. Mount the Engine
+
+In your `config/routes.rb`:
+
+```ruby
+mount RailsMap::Engine, at: '/api-doc'
+```
+
+### 2. Create Configuration File
+
+Create `config/initializers/rails_map.rb` in your Rails application:
+
+```ruby
+RailsMap.configure do |config|
+  config.app_name = 'Your App Name'
+  config.theme_color = '#3B82F6'
+  
+  # Add authentication
+  config.authenticate_with = proc {
+    # Your authentication logic here
+  }
+end
+```
+
+## Authentication Examples
+
+### Option 1: Built-in Authentication (Recommended)
+
+If you don't use Devise, use the built-in authentication system.
+
+**Setup:**
+
+1. Install with authentication:
+```bash
+rails g rails_map:install
+rails db:migrate
+```
+
+2. Create admin user(s):
+```bash
+rails c
+RailsMap::User.create!(username: 'admin', password: 'your_secure_password')
+RailsMap::User.create!(username: 'developer', password: 'another_password')
+```
+
+3. Enable in configuration:
+```ruby
+config.authenticate_with = proc {
+  RailsMap::Auth.authenticate(self)
+}
+```
+
+4. Restart server and visit `/api-doc` - you'll be prompted for username/password
+
+**Managing Users:**
+
+```ruby
+# Create user
+RailsMap::User.create!(username: 'john', password: 'password123')
+
+# Update password
+user = RailsMap::User.find_by(username: 'john')
+user.update!(password: 'new_password')
+
+# Delete user
+RailsMap::User.find_by(username: 'john').destroy
+
+# List all users
+RailsMap::User.all.pluck(:username)
+```
+
+### Option 2: Devise Authentication
+
+If you're using Devise:
+
+```ruby
+config.authenticate_with = proc {
+  authenticate_user!
+}
+```
+
+Or restrict to admins only:
+
+```ruby
+config.authenticate_with = proc {
+  authenticate_user!
+  redirect_to root_path, alert: 'Not authorized' unless current_user.admin?
+}
+```
+
+### Option 3: HTTP Basic Authentication
+
+Simple username/password protection:
+
+```ruby
+config.authenticate_with = proc {
+  authenticate_or_request_with_http_basic do |username, password|
+    username == 'admin' && password == 'secret'
+  end
+}
+```
+
+With environment variables (recommended):
+
+```ruby
+config.authenticate_with = proc {
+  authenticate_or_request_with_http_basic do |username, password|
+    username == ENV['DOC_USERNAME'] && password == ENV['DOC_PASSWORD']
+  end
+}
+```
+
+### Option 4: Environment-Based Protection
+
+Protect only in production:
+
+```ruby
+config.authenticate_with = proc {
+  if Rails.env.production?
+    authenticate_or_request_with_http_basic do |username, password|
+      username == ENV['DOC_USERNAME'] && password == ENV['DOC_PASSWORD']
+    end
+  end
+}
+```
+
+### Option 5: Custom Authentication Logic
+
+Use any custom logic:
+
+```ruby
+config.authenticate_with = proc {
+  # Check session
+  unless session[:authenticated]
+    redirect_to login_path
+    return
+  end
+  
+  # Check user role
+  unless current_user&.has_role?(:developer)
+    render plain: 'Unauthorized', status: :unauthorized
+  end
+}
+```
+
+### Option 6: IP Whitelist
+
+Restrict by IP address:
+
+```ruby
+config.authenticate_with = proc {
+  allowed_ips = ['127.0.0.1', '::1', '10.0.0.0/8']
+  
+  unless allowed_ips.any? { |ip| IPAddr.new(ip).include?(request.remote_ip) }
+    render plain: 'Forbidden', status: :forbidden
+  end
+}
+```
+
+## Testing Authentication
+
+After configuring authentication:
+
+1. Restart your Rails server
+2. Visit `http://localhost:3000/api-doc`
+3. You should be prompted to authenticate
+
+## No Authentication (Development Only)
+
+To disable authentication during development, simply don't set `authenticate_with` or use:
+
+```ruby
+config.authenticate_with = nil
+```
+
+Or conditionally:
+
+```ruby
+unless Rails.env.development?
+  config.authenticate_with = proc {
+    # Your auth logic
+  }
+end
+```
+
+## Troubleshooting
+
+### Infinite Redirect Loop
+
+Make sure your authentication logic doesn't redirect to itself:
+
+```ruby
+# BAD - will cause infinite loop if not careful
+config.authenticate_with = proc {
+  redirect_to login_path unless logged_in?
+}
+
+# GOOD - check if already on login page
+config.authenticate_with = proc {
+  redirect_to login_path unless logged_in? || request.path == login_path
+}
+```
+
+### Helper Methods Not Available
+
+The authentication block runs in the controller context, so you have access to:
+- `request`
+- `session`
+- `cookies`
+- `params`
+- `redirect_to`
+- `render`
+- Any helper methods from your application
+
+If a method isn't available, you may need to include it in the engine controller or use a different approach.

data/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- API parameter detection and display for all routes
+  - Automatic extraction of path parameters (e.g., `:id`, `:user_id`)
+  - Query parameter detection for GET and DELETE requests
+  - Request body parameter detection for POST, PUT, and PATCH requests
+  - Intelligent type inference (string, integer, boolean, datetime, email, etc.)
+  - Required/optional parameter indication
+  - Parameter location display (path, query, or body)
+  - Expandable parameter details in routes and controller views
+- Controller action analysis to extract permitted parameters
+- Support for strong parameters pattern (`params.require().permit()`)
+- Parameter documentation in both live and static HTML documentation
+
+## [1.1.0] - 2026-02-10
+
+### Added
+
+- Live documentation via Rails Engine mounting at `/api-doc`
+- Built-in authentication system (no Devise required) with `RailsMap::User` model
+- Generator for easy installation: `rails g rails_map:install [--skip-auth]`
+  - Authentication enabled by default for security
+  - Use `--skip-auth` flag to disable authentication
+  - Automatically creates configuration file
+  - Automatically mounts engine in routes
+  - Automatically creates user migration (unless `--skip-auth`)
+  - Automatically adds `/doc/api` to `.gitignore`
+- Authentication support with `authenticate_with` configuration option
+- `RailsMap::Auth` helper module for authentication
+- Example configuration file with authentication examples
+- Comprehensive authentication guide (`AUTHENTICATION.md`)
+- Quick start guide (`QUICKSTART.md`)
+
+### Changed
+
+- Improved card layout design with hover effects
+- Better visual hierarchy for controller and model cards
+- Enhanced responsive grid layout (350px min card width)
+- Updated card styling with better spacing and shadows
+
+### Fixed
+
+- Route constraint issue preventing access to namespaced controllers
+- Support for nested controller names with slashes (e.g., `admin/users`)
+
+## [1.0.0] - 2026-02-09
+
+### Added
+
+- Initial release
+- Route parsing and documentation generation
+- Model parsing with columns, associations, validations, and scopes
+- HTML documentation generation with responsive design
+- Rake tasks: `doc:generate`, `doc:open`, `doc:clean`
+- Customizable configuration options:
+  - `output_dir` - Output directory for generated documentation
+  - `app_name` - Application name displayed in documentation
+  - `theme_color` - Theme color for UI customization
+  - `include_timestamps` - Toggle timestamp columns in model docs
+  - `include_validations` - Toggle validations in model docs
+  - `include_scopes` - Toggle scopes in model docs
+- Color-coded HTTP method badges (GET, POST, PUT, PATCH, DELETE)
+- Association type badges (belongs_to, has_many, has_one, has_and_belongs_to_many)
+- Statistics dashboard with controller, route, and model counts
+- Interlinked documentation pages for easy navigation
+- Dark theme UI with modern design

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "rspec", "~> 3.0"
+  gem "rubocop", "~> 1.0"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026
+
+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/QUICKSTART.md

@@ -0,0 +1,156 @@
+# Quick Start Guide
+
+🌐 **[Homepage](https://rails-map.netlify.app)** | 📚 **[Full Documentation](https://github.com/ArshdeepGrover/rails-map#readme)**
+
+Get up and running with RailsMap in under 5 minutes!
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'rails_map'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Setup
+
+### Default Installation (With Authentication - Recommended)
+
+1. Run the generator:
+```bash
+rails g rails_map:install
+rails db:migrate
+```
+
+This automatically:
+- ✅ Creates `config/initializers/rails_map.rb` with auth enabled
+- ✅ Mounts the engine in `config/routes.rb`
+- ✅ Creates user migration
+- ✅ Adds `/doc/api` to `.gitignore`
+
+2. Create an admin user:
+```bash
+rails c
+RailsMap::User.create!(username: 'admin', password: 'your_secure_password')
+exit
+```
+
+3. Start your server:
+```bash
+rails s
+```
+
+4. Visit `http://localhost:3000/api-doc` and login with your credentials
+
+**That's it!** 🎉 Secure by default!
+
+---
+
+### Skip Authentication (Development Only)
+
+1. Run the generator with --skip-auth flag:
+```bash
+rails g rails_map:install --skip-auth
+```
+
+2. Start your server:
+```bash
+rails s
+```
+
+3. Visit: `http://localhost:3000/api-doc`
+
+**No authentication required!** Use only in development.
+
+---
+
+## Customization
+
+### Change Theme Color
+
+In `config/initializers/rails_map.rb`:
+
+```ruby
+config.theme_color = '#FF6B6B'  # Any valid CSS color
+```
+
+### Change App Name
+
+```ruby
+config.app_name = 'My Awesome API'
+```
+
+### Hide Timestamps in Models
+
+```ruby
+config.include_timestamps = false
+```
+
+## Managing Users (Built-in Auth)
+
+### Create User
+```ruby
+RailsMap::User.create!(username: 'developer', password: 'password123')
+```
+
+### Change Password
+```ruby
+user = RailsMap::User.find_by(username: 'developer')
+user.update!(password: 'new_password')
+```
+
+### Delete User
+```ruby
+RailsMap::User.find_by(username: 'developer').destroy
+```
+
+### List All Users
+```ruby
+RailsMap::User.all.pluck(:username)
+```
+
+## Static HTML Generation (Optional)
+
+If you want to generate static HTML files instead of using the live engine:
+
+```bash
+rails doc:generate  # Generate HTML files
+rails doc:open      # Open in browser
+rails doc:clean     # Remove generated files
+```
+
+Files are generated in `doc/api/` by default.
+
+## Troubleshooting
+
+### Can't access /api-doc
+- Make sure you've mounted the engine in `config/routes.rb`
+- Restart your Rails server
+
+### Authentication not working
+- Verify you've run migrations: `rails db:migrate`
+- Check that you've created a user
+- Ensure authentication is enabled in the initializer
+
+### Controllers with slashes not showing
+- Update the gem to the latest version
+- The route constraint issue has been fixed
+
+## Next Steps
+
+- Read [AUTHENTICATION.md](AUTHENTICATION.md) for advanced authentication options
+- Read [README.md](README.md) for complete documentation
+- Customize your theme color and app name
+- Add authentication for production deployments
+
+## Need Help?
+
+- Check the [README.md](README.md) for detailed documentation
+- Review [AUTHENTICATION.md](AUTHENTICATION.md) for authentication setup
+- Open an issue on [GitHub](https://github.com/ArshdeepGrover/rails-map/issues)

data/README.md

@@ -0,0 +1,178 @@
+# Rails Map
+
+🌐 **[Homepage](https://rails-map.netlify.app)** | 📦 **[RubyGems](https://rubygems.org/gems/rails_map)** | 🐙 **[GitHub](https://github.com/ArshdeepGrover/rails-map)**
+
+Automatically generates interactive API documentation for Rails by mapping routes, controllers, and models. Zero configuration—just install and go.
+
+- **Routes** - All routes grouped by controller with HTTP methods, paths, and route names
+- **Controllers** - Separate page for each controller with detailed route information
+- **Models** - Separate page for each model with columns, associations, validations, and scopes
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rails_map'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+### Quick Setup (With Authentication - Default)
+
+Run the installer:
+
+```bash
+rails g rails_map:install
+```
+
+Set environment variables (optional):
+
+```bash
+export RAILS_MAP_USERNAME=admin
+export RAILS_MAP_PASSWORD=your_secure_password
+```
+
+Or add to `.env` file:
+
+```
+RAILS_MAP_USERNAME=admin
+RAILS_MAP_PASSWORD=your_secure_password
+```
+
+This automatically:
+
+- ✅ Creates `config/initializers/rails_map.rb` with authentication enabled
+- ✅ Mounts the engine at `/api-doc`
+- ✅ Adds `/doc/api` to `.gitignore`
+- ✅ Uses default credentials (admin/password) if ENV variables not set
+
+Start your server and visit `http://localhost:3000/api-doc` - you'll be prompted to login!
+
+### Setup Without Authentication
+
+If you don't want authentication (development only recommended):
+
+```bash
+rails g rails_map:install --skip-auth
+```
+
+This will:
+
+- ✅ Create the configuration file (auth disabled)
+- ✅ Mount the engine at `/api-doc`
+- ✅ Add `/doc/api` to `.gitignore`
+
+Start your server and visit `/api-doc` - no login required!
+
+## Usage
+
+### Live Documentation (Recommended)
+
+Mount the engine in your `config/routes.rb`:
+
+```ruby
+mount RailsMap::Engine, at: '/api-doc'
+```
+
+Then visit `http://localhost:3000/api-doc` in your browser to see live documentation.
+
+### Static HTML Generation
+
+Run the following rake task to generate static HTML documentation:
+
+```bash
+rails doc:generate
+```
+
+This will generate HTML documentation in `doc/api/` directory.
+
+### Open Documentation in Browser
+
+```bash
+rails doc:open
+```
+
+### Clean Generated Documentation
+
+```bash
+rails doc:clean
+```
+
+## Configuration
+
+Create an initializer `config/initializers/rails_map.rb`:
+
+```ruby
+RailsMap.configure do |config|
+  # Output directory for generated documentation
+  config.output_dir = Rails.root.join('doc', 'api').to_s
+
+  # Application name displayed in the documentation
+  config.app_name = 'My Application'
+
+  # Theme color (any valid CSS color)
+  config.theme_color = '#3B82F6'
+
+  # Include timestamp columns (created_at, updated_at) in model documentation
+  config.include_timestamps = true
+
+  # Include model validations in documentation
+  config.include_validations = true
+
+  # Include model scopes in documentation
+  config.include_scopes = true
+
+  # Authentication - Protect documentation with authentication
+  # Uses environment variables: RAILS_MAP_USERNAME and RAILS_MAP_PASSWORD
+  # Defaults to username: admin, password: password
+
+  config.authenticate_with = proc {
+    RailsMap::Auth.authenticate(self)
+  }
+
+  # Option 2: Devise
+  # config.authenticate_with = proc {
+  #   authenticate_user!
+  # }
+
+  # Option 3: Custom logic
+  # config.authenticate_with = proc {
+  #   redirect_to root_path unless current_user&.admin?
+  # }
+end
+```
+
+## Features
+
+- 📱 **Responsive Design** - Works on desktop and mobile
+- 🎨 **Customizable Theme** - Change the primary color to match your brand
+- 🔗 **Interlinked Pages** - Easy navigation between related models and controllers
+- 🏷️ **HTTP Method Badges** - Color-coded badges for different HTTP methods
+- 📊 **Statistics Dashboard** - Quick overview of your application structure
+- 🔍 **Association Type Badges** - Visual distinction for different association types
+- 📝 **API Parameter Detection** - Automatically extracts and displays parameters for each route
+  - Path parameters (`:id`, `:user_id`, etc.)
+  - Query parameters for GET/DELETE requests
+  - Request body parameters for POST/PUT/PATCH requests
+  - Type inference (string, integer, boolean, datetime, etc.)
+  - Required/optional indication
+  - Parameter location (path, query, body)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ArshdeepGrover/rails-map.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec