rails-autodoc 0.1.0

data/README.md

@@ -0,0 +1,111 @@
+# rails-autodoc
+
+Auto-generate OpenAPI 3.0 documentation from Rails routes, strong params, database schemas, and serializers.
+
+**Problem:** Tools like rswag require maintaining RSpec specs that drift in legacy projects.
+
+**Solution:** `rails-autodoc` reads the code you already maintain to ship features: `routes.rb`, `permit(...)`, and `db/schema.rb`.
+
+## Quick start
+
+Add to your Gemfile:
+
+```ruby
+gem "rails-autodoc", group: :development
+```
+
+Install:
+
+```bash
+bundle install
+rails generate rails_autodoc:install
+rake autodoc:generate
+```
+
+Open interactive docs:
+
+```
+http://localhost:3000/api-docs
+```
+
+## What gets generated automatically
+
+| Feature | Support |
+|---------|---------|
+| Paths and HTTP verbs | Yes |
+| Path parameters | Yes |
+| Request body fields from strong params | Yes |
+| Request field types from DB schema | Best effort |
+| Query params from `params[:foo]` usage | Best effort |
+| Response schemas | Serializer-aware, best effort |
+| Validation rules / enums | Via annotation DSL |
+
+## Configuration
+
+```ruby
+# config/initializers/rails_autodoc.rb
+RailsAutodoc.configure do |config|
+  config.title = "My API"
+  config.version = "1.0.0"
+  config.mount_path = "/api-docs"
+  config.output_path = Rails.root.join("openapi/openapi.yaml")
+  config.exclude_paths = [%r{^/rails/}, %r{^/api-docs}]
+end
+```
+
+## Annotation DSL (optional)
+
+Use when inference is not enough:
+
+```ruby
+class Api::V1::UsersController < ApplicationController
+  swagger_doc action: :create do
+    summary "Create a user"
+    body_param :role, :string, enum: %w[admin user]
+    response 201, ref: "User"
+    response 422, ref: "ValidationError"
+  end
+end
+```
+
+## Rake tasks
+
+| Task | Description |
+|------|-------------|
+| `rake autodoc:generate` | Write OpenAPI YAML to configured output path |
+| `rake autodoc:verify` | Fail if generated spec differs from committed file |
+| `rake autodoc:routes` | Print inferred operations |
+
+## CI integration
+
+```yaml
+- run: bundle exec rake autodoc:verify
+```
+
+## Comparison
+
+| Tool | Approach | Maintenance |
+|------|----------|-------------|
+| FastAPI | Types are the spec | Zero drift |
+| rswag | RSpec DSL drives docs | High |
+| swagger-blocks | Manual annotations | High |
+| rails-autodoc | Convention inference | Low |
+
+## Rails compatibility
+
+Officially tested with Rails 5.2, 6.1, 7.0, 7.1, and 8.0 via Appraisal.
+
+## Documentation
+
+Full docs live in [`docs/`](docs/index.md):
+
+- [Getting Started](docs/getting-started.md)
+- [Configuration](docs/configuration.md)
+- [Inference Rules](docs/inference-rules.md)
+- [Annotation DSL](docs/annotation-dsl.md)
+- [Limitations](docs/limitations.md)
+- [Migration from rswag](docs/migration-from-rswag.md)
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+task :environment do
+  require "rails"
+  require "rails_autodoc"
+  require "combustion"
+
+  Combustion.path = "spec/dummy"
+  Combustion.initialize! :all unless Combustion::Application.initialized?
+end
+
+load File.expand_path("lib/rails_autodoc/tasks/autodoc.rake", __dir__)
+
+namespace :appraisal do
+  desc "Run specs against all Rails versions"
+  task :spec do
+    sh "bundle exec appraisal rake spec"
+  end
+end

data/app/controllers/rails_autodoc/spec_controller.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RailsAutodoc
+  class SpecController < ActionController::Base
+    def show
+      spec = cached_spec
+      render json: spec
+    end
+
+    def ui
+      render html: swagger_ui_html.html_safe
+    end
+
+    private
+
+    def cached_spec
+      return self.class.cached_spec if RailsAutodoc.config.cache_spec_in_dev && self.class.cached_spec
+
+      self.class.cached_spec = Generator.new.generate
+    end
+
+    def swagger_ui_html
+      spec_url = "#{RailsAutodoc.config.mount_path}/spec.json"
+      <<~HTML
+        <!DOCTYPE html>
+        <html lang="en">
+          <head>
+            <meta charset="UTF-8" />
+            <title>#{RailsAutodoc.config.title} API Docs</title>
+            <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
+          </head>
+          <body>
+            <div id="swagger-ui"></div>
+            <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+            <script>
+              window.onload = function() {
+                SwaggerUIBundle({
+                  url: "#{spec_url}",
+                  dom_id: "#swagger-ui"
+                });
+              };
+            </script>
+          </body>
+        </html>
+      HTML
+    end
+
+    class << self
+      attr_accessor :cached_spec
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+RailsAutodoc::Engine.routes.draw do
+  get "/", to: "spec#ui"
+  get "/spec.json", to: "spec#show"
+end

data/docs/annotation-dsl.md

@@ -0,0 +1,56 @@
+# Annotation DSL
+
+Use annotations when inference is incomplete.
+
+## Basic usage
+
+```ruby
+class Api::V1::UsersController < ApplicationController
+  swagger_doc action: :create do
+    summary "Create a user"
+    description "Creates a user with the provided attributes"
+    tag "Users"
+    deprecated false
+  end
+end
+```
+
+## Request overrides
+
+```ruby
+swagger_doc action: :create do
+  body_param :role, :string, enum: %w[admin user]
+  query_param :include, :string, required: false
+
+  request_body type: :object, properties: {
+    user: { type: :object }
+  }
+end
+```
+
+## Response overrides
+
+```ruby
+swagger_doc action: :create do
+  response 201, ref: "User"
+  response 422, ref: "ValidationError"
+end
+```
+
+## Security
+
+```ruby
+swagger_doc action: :index do
+  security :bearer_auth
+end
+```
+
+## Exclude endpoints
+
+```ruby
+swagger_doc action: :debug do
+  exclude true
+end
+```
+
+Annotations always override inferred values for the same operation.

data/docs/architecture.md

@@ -0,0 +1,37 @@
+# Architecture
+
+## Pipeline
+
+1. `RouteInspector` discovers operations from Rails routes
+2. `StrongParamsParser` extracts request schemas from controller AST
+3. `SchemaMapper` maps ActiveRecord columns to OpenAPI types
+4. `ResponseInferencer` inspects render/head calls
+5. Serializer adapters enrich response schemas
+6. `Registry` merges `swagger_doc` overrides
+7. `OpenapiSpecBuilder` assembles OpenAPI 3.0.3 output
+8. `Generator` writes YAML or serves JSON via the engine
+
+## Key classes
+
+| Class | Responsibility |
+|-------|------------------|
+| `RailsAutodoc::RouteInspector` | Route discovery |
+| `RailsAutodoc::StrongParamsParser` | AST permit extraction |
+| `RailsAutodoc::SchemaMapper` | DB schema mapping |
+| `RailsAutodoc::ResponseInferencer` | Response inference |
+| `RailsAutodoc::OpenapiSpecBuilder` | OpenAPI assembly |
+| `RailsAutodoc::Generator` | Orchestration and export |
+| `RailsAutodoc::Engine` | Swagger UI and live spec |
+
+## Extension points
+
+- Serializer adapters under `lib/rails_autodoc/serializers/`
+- Annotation DSL via `swagger_doc`
+- Configuration in `RailsAutodoc.configure`
+
+## Testing strategy
+
+- Combustion dummy Rails app in `spec/dummy/`
+- Unit specs per component
+- Appraisal matrix for Rails 5.2 through 8.0
+- Golden OpenAPI fixtures for regression testing

data/docs/ci-integration.md

@@ -0,0 +1,32 @@
+# CI Integration
+
+Prevent documentation drift by verifying the committed OpenAPI file matches generated output.
+
+## Local verify
+
+```bash
+rake autodoc:generate
+rake autodoc:verify
+```
+
+## GitHub Actions
+
+The install generator adds `.github/workflows/autodoc-verify.yml`:
+
+```yaml
+- run: bundle exec rake autodoc:verify
+```
+
+## Recommended workflow
+
+1. Commit `openapi/openapi.yaml`
+2. Run `autodoc:verify` in CI on every pull request
+3. Regenerate locally when routes or strong params change
+
+## Debugging inferred routes
+
+```bash
+rake autodoc:routes
+```
+
+Prints verb, path, controller, and action for every discovered operation.

data/docs/configuration.md

@@ -0,0 +1,48 @@
+# Configuration
+
+Configure the gem in `config/initializers/rails_autodoc.rb`:
+
+```ruby
+RailsAutodoc.configure do |config|
+  config.title = "My App API"
+  config.version = "1.0.0"
+  config.description = "Auto-generated API documentation"
+  config.mount_path = "/api-docs"
+  config.output_path = Rails.root.join("openapi/openapi.yaml")
+  config.exclude_paths = [%r{^/rails/}, %r{^/api-docs}]
+  config.cache_spec_in_dev = true
+end
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `title` | `"Rails API"` | OpenAPI info title |
+| `version` | `"1.0.0"` | OpenAPI info version |
+| `description` | auto | OpenAPI info description |
+| `mount_path` | `"/api-docs"` | Engine mount path |
+| `output_path` | `openapi/openapi.yaml` | Static export path |
+| `exclude_paths` | internal routes | Regex list of paths to skip |
+| `include_engines` | `[]` | Additional engines to scan |
+| `default_security` | `nil` | Default security scheme key |
+| `security_schemes` | `{}` | OpenAPI security scheme definitions |
+| `cache_spec_in_dev` | `true` | Cache live spec in development |
+| `servers` | localhost | OpenAPI servers array |
+
+## Security example
+
+```ruby
+config.security_schemes = {
+  "bearer_auth" => {
+    "type" => "http",
+    "scheme" => "bearer",
+    "bearerFormat" => "JWT"
+  }
+}
+config.default_security = :bearer_auth
+```
+
+## Production guidance
+
+Serve static `openapi/openapi.yaml` in production rather than mounting the engine publicly unless docs should be externally accessible.

data/docs/faq.md

@@ -0,0 +1,29 @@
+# FAQ
+
+## Why not use FastAPI-style type-driven docs?
+
+Rails APIs rarely declare request/response contracts in types. `rails-autodoc` meets teams where they are: strong params and routes.
+
+## Will docs drift?
+
+Static exports can drift if you forget to regenerate. Use `rake autodoc:verify` in CI to catch drift.
+
+## How accurate are generated schemas?
+
+Good for endpoint discovery, request field names, and common REST patterns. Validation rules, enums, and complex response shapes need DSL overrides or serializer gems.
+
+## Does it work on legacy Rails 5 apps?
+
+Yes. The gem targets Rails 5.2 through 8.x and uses CDN-based Swagger UI to avoid asset pipeline dependencies.
+
+## Can I hide internal routes?
+
+Yes. Use `config.exclude_paths` regexes or `swagger_doc { exclude true }`.
+
+## Does it replace rswag contract tests?
+
+No. It replaces documentation maintenance burden. Keep contract tests if you rely on them for response validation.
+
+## What OpenAPI version is generated?
+
+OpenAPI 3.0.3.

data/docs/getting-started.md

@@ -0,0 +1,54 @@
+# Getting Started
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "rails-autodoc", group: :development
+```
+
+Run Bundler:
+
+```bash
+bundle install
+```
+
+## Install generator
+
+```bash
+rails generate rails_autodoc:install
+```
+
+This creates:
+
+- `config/initializers/rails_autodoc.rb`
+- `openapi/` output directory
+- Engine mount at `/api-docs`
+- `.github/workflows/autodoc-verify.yml`
+
+## Generate documentation
+
+```bash
+rake autodoc:generate
+```
+
+Output defaults to `openapi/openapi.yaml`.
+
+## View interactive docs
+
+Start Rails and visit:
+
+```
+http://localhost:3000/api-docs
+```
+
+The engine serves Swagger UI and a live spec at `/api-docs/spec.json`.
+
+## Verify in CI
+
+```bash
+rake autodoc:verify
+```
+
+Commit the generated YAML and run this task in CI to prevent documentation drift.

data/docs/index.md

@@ -0,0 +1,21 @@
+# rails-autodoc
+
+Generate OpenAPI 3.0 documentation from Rails conventions — routes, strong params, database schemas, and serializers.
+
+## Why this gem exists
+
+Legacy Rails APIs often have outdated rswag specs. `rails-autodoc` generates docs from files teams already update to ship features:
+
+- `config/routes.rb`
+- `params.require(...).permit(...)`
+- `db/schema.rb`
+
+## Features
+
+- Zero-config baseline documentation
+- Optional `swagger_doc` DSL for edge cases
+- Swagger UI at `/api-docs`
+- CI drift detection via `rake autodoc:verify`
+- Rails 5.2 through 8.x support
+
+See [Getting Started](getting-started.md) to install the gem.

data/docs/inference-rules.md

@@ -0,0 +1,74 @@
+# Inference Rules
+
+`rails-autodoc` builds OpenAPI operations from Rails conventions.
+
+## Routes
+
+Source: `Rails.application.routes`
+
+Extracted data:
+
+- HTTP verb
+- Path template (`/users/:id` -> `/users/{id}`)
+- Controller and action
+- Path parameters
+- Tags from controller namespace
+
+## Strong params
+
+Source: controller AST via `parser`
+
+Supported patterns:
+
+```ruby
+params.require(:user).permit(:name, :email)
+params.require(:user).permit(:name, address: [:street, :city])
+params.require(:user).permit(tags: [])
+```
+
+Action mapping:
+
+- Looks for `*_params` method calls inside the action
+- Falls back to the first `*_params` method in the controller
+
+## Database schema
+
+Source: `db/schema.rb`
+
+- Maps model attributes to OpenAPI types
+- Applies types to request fields when names match model columns
+- Generates `components.schemas` entries for ActiveRecord models
+
+## Query params
+
+Source: AST scan of action body
+
+Detects:
+
+- `params[:page]`
+- `params.fetch(:filter)`
+
+Defaults to optional string parameters.
+
+## Responses
+
+Source: AST scan of `render` and `head` calls
+
+Examples:
+
+- `render json: @user` -> model-based schema reference
+- `render json: user, status: :created` -> HTTP 201
+- `head :no_content` -> HTTP 204
+
+Default status by verb when no render call is found:
+
+| Verb | Status |
+|------|--------|
+| GET | 200 |
+| POST | 201 |
+| PUT/PATCH | 200 |
+| DELETE | 204 |
+
+## Serializers
+
+If Alba, Blueprinter, or ActiveModel::Serializer is present, response schemas use serializer field definitions.

data/docs/limitations.md

@@ -0,0 +1,34 @@
+# Limitations
+
+`rails-autodoc` is convention-driven. It is not a replacement for contract-first API design.
+
+## Known gaps
+
+| Scenario | Behavior |
+|----------|----------|
+| `params.permit!` | Not parsed; empty or generic schema |
+| Dynamic param keys | Not inferred |
+| Params in service objects | Not inferred |
+| GraphQL endpoints | Out of scope |
+| Grape APIs | Out of scope for v1 |
+| Conditional strong params | Best effort only |
+| Complex serializer logic | Field list only, no computed attribute types |
+
+## Accuracy expectations
+
+- Baseline without annotations: ~60-70% useful coverage
+- With light DSL overrides: ~90%+ for most REST APIs
+
+## When to use annotations
+
+- Enum values
+- Custom response codes
+- Authentication requirements
+- Non-standard request bodies
+- Hiding internal/debug endpoints
+
+## When not to use this gem
+
+- Public APIs requiring strict contract guarantees
+- APIs with minimal Rails conventions
+- Greenfield projects where OpenAPI-first tooling is available

data/docs/migration-from-rswag.md

@@ -0,0 +1,42 @@
+# Migration from rswag
+
+## Philosophy difference
+
+| rswag | rails-autodoc |
+|-------|---------------|
+| Tests drive docs | Conventions drive docs |
+| High accuracy when maintained | Good accuracy with low maintenance |
+| Requires RSpec DSL | Works without extra specs |
+
+## Coexistence
+
+You can run both during migration:
+
+1. Install `rails-autodoc`
+2. Generate baseline docs with `rake autodoc:generate`
+3. Compare against existing rswag output
+4. Remove rswag once satisfied
+
+## Mapping concepts
+
+| rswag | rails-autodoc |
+|-------|---------------|
+| `path` | inferred from routes |
+| `parameter` | inferred from strong params / query usage |
+| `response` | inferred from render calls or `swagger_doc` |
+| `swagger_helper` config | `RailsAutodoc.configure` |
+
+## Recommended migration path for legacy apps
+
+1. Run `rails generate rails_autodoc:install`
+2. Generate docs on day one without changing controllers
+3. Add `swagger_doc` only where inference is wrong
+4. Add `autodoc:verify` to CI
+5. Deprecate outdated rswag specs
+
+## What you can delete after migration
+
+- rswag request specs used only for documentation
+- Manual swagger YAML maintained separately from code
+
+Keep rswag if you also use it for contract testing against the generated spec.

data/docs/serializer-support.md

@@ -0,0 +1,25 @@
+# Serializer Support
+
+`rails-autodoc` detects serializer gems at runtime and uses them for response schemas.
+
+## Supported adapters
+
+| Gem | Detection | Schema source |
+|-----|-----------|---------------|
+| Alba | `defined?(Alba)` | declared attributes |
+| Blueprinter | `defined?(Blueprinter)` | `fields` hash |
+| ActiveModel::Serializer | `defined?(ActiveModel::Serializer)` | `_attributes` |
+
+Adapters are optional soft dependencies. If no serializer gem is present, responses fall back to model schemas or generic objects.
+
+## Adding a custom adapter
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-a-serializer-adapter).
+
+Each adapter implements:
+
+- `#detect?`
+- `#attributes_for(serializer_class)`
+- `#schema_for(serializer_class)`
+
+Register new adapters in `RailsAutodoc::Serializers::Registry`.

data/lib/generators/rails_autodoc/install_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RailsAutodoc
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install rails-autodoc configuration, output directory, and optional CI workflow"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/rails_autodoc.rb"
+      end
+
+      def create_output_directory
+        empty_directory "openapi"
+        create_file "openapi/.keep"
+      end
+
+      def mount_engine
+        route <<~ROUTE
+
+          # Auto-generated API documentation (development/staging recommended)
+          mount RailsAutodoc::Engine => "/api-docs"
+        ROUTE
+      end
+
+      def create_ci_workflow
+        template "autodoc-verify.yml", ".github/workflows/autodoc-verify.yml"
+      end
+    end
+  end
+end