If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Apipie/apipie-rails shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 6mo ago
• 25+ active contributors
• Distributed ownership (top contributor 26% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 6mo ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Apipie/apipie-rails repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Apipie/apipie-rails.

What it runs against: a local clone of Apipie/apipie-rails — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Apipie/apipie-rails | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 214 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Apipie/apipie-rails. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Apipie/apipie-rails.git
#   cd apipie-rails
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Apipie/apipie-rails and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Apipie/apipie-rails(\\.git)?\\b" \\
  && ok "origin remote is Apipie/apipie-rails" \\
  || miss "origin remote is not Apipie/apipie-rails (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/apipie-rails.rb" \\
  && ok "lib/apipie-rails.rb" \\
  || miss "missing critical file: lib/apipie-rails.rb"
test -f "lib/apipie/application.rb" \\
  && ok "lib/apipie/application.rb" \\
  || miss "missing critical file: lib/apipie/application.rb"
test -f "lib/apipie/dsl_definition.rb" \\
  && ok "lib/apipie/dsl_definition.rb" \\
  || miss "missing critical file: lib/apipie/dsl_definition.rb"
test -f "lib/apipie/configuration.rb" \\
  && ok "lib/apipie/configuration.rb" \\
  || miss "missing critical file: lib/apipie/configuration.rb"
test -f "app/controllers/apipie/apipies_controller.rb" \\
  && ok "app/controllers/apipie/apipies_controller.rb" \\
  || miss "missing critical file: app/controllers/apipie/apipies_controller.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 214 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~184d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Apipie/apipie-rails"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Apipie-rails is a Ruby on Rails engine and DSL that lets you document your RESTful APIs directly in controller code using Ruby syntax rather than comments or separate documentation files. It generates interactive HTML documentation and JSON endpoints (at /apipie and /apipie.json by default) that stay in sync with your actual endpoint definitions, eliminating the friction of maintaining separate API docs. Rails engine architecture: app/controllers/apipie/apipies_controller.rb serves the documentation UI, app/views/apipie/apipies/ contains ERB templates for HTML rendering (index.html.erb, resource.html.erb, method.html.erb, plain.html.erb), and app/public/apipie/ houses static assets (bundled Bootstrap, jQuery, prettify.js). The core DSL is likely in a lib/ directory not fully listed, where decorators or helper methods are mixed into ActionController::Base.

Rails developers building and maintaining RESTful APIs who need to document endpoints, parameters, error responses, and deprecations without learning a new markup language or maintaining docs in separate files. Also useful for API consumers who need to browse live, up-to-date endpoint specifications.

Production-ready and actively maintained. The project has clear CI/CD via GitHub Actions (build.yml, rubocop.yml workflows), follows Ruby standards (rubocop configuration present), includes Apache 2.0 and MIT licensing, and has a stable Gem release on rubygems.org. The presence of CHANGELOG.md, contributor graphs, and multiple releases indicates sustained development.

Low risk for established Rails projects. Single-maintainer concerns are mitigated by an active contributor community visible in GitHub graphs. The codebase is lightweight (~475KB Ruby) with minimal external dependencies (gemspec not fully visible but standard Rails plugin approach). Main risk: tight coupling to Rails version; ensure your Rails version is supported by checking CHANGELOG.md for compatibility notes.

Active linting and code quality work via rubocop-challenger.yml and rubocop.yml (automating style improvements). The presence of PROPOSAL_FOR_RESPONSE_DESCRIPTIONS.md suggests ongoing feature discussion around response documentation. Build CI is active and passing (badge in README).

git clone https://github.com/Apipie/apipie-rails.git
cd apipie-rails
bundle install
bundle exec rake

Then explore spec/ (via Gemfile's test setup with .rspec config) to understand the DSL, or clone the demo app at https://github.com/Apipie/apipie-demo to see live usage.

Daily commands: This is a gem/plugin, not a standalone app. To test locally: bundle exec rake (runs tests, inferred from .rspec config). To use in a Rails app: add gem 'apipie-rails' to Gemfile, bundle install, run rails g apipie:install (generator not in file list but standard Rails pattern), then start Rails (rails s) and visit http://localhost:3000/apipie.

• lib/apipie-rails.rb — Entry point for the entire gem; initializes the Rails engine and loads all core modules
• lib/apipie/application.rb — Core application object that manages API documentation state, resources, and method descriptions
• lib/apipie/dsl_definition.rb — Defines the DSL macros used in controllers to declare API endpoints and their documentation
• lib/apipie/configuration.rb — Centralizes all gem configuration options and initialization settings
• app/controllers/apipie/apipies_controller.rb — Main Rails controller rendering documentation views and serving API metadata endpoints
• lib/apipie/generator/swagger/method_description.rb — Converts Apipie method descriptions to OpenAPI/Swagger specifications for modern tooling
• lib/apipie/extractor/collector.rb — Extracts documentation metadata from routes and controllers at runtime

Add a new API endpoint to documentation

1. Open your Rails controller and add the api! block with param, error, and description calls (app/controllers/your_controller.rb)
2. Define parameter and error types in the api block using DSL macros from dsl_definition.rb (lib/apipie/dsl_definition.rb)
3. Restart the Rails server; Apipie automatically collects the DSL metadata via the extractor (lib/apipie/extractor/collector.rb)
4. Visit /api/docs in your app to see the new endpoint rendered in the documentation UI (app/views/apipie/apipies/index.html.erb)
5. To expose as OpenAPI, run generation task which uses the swagger converter (lib/apipie/generator/swagger/method_description.rb)

Add a new configuration option

1. Add the configuration key and default value in the Apipie::Configuration class (lib/apipie/configuration.rb)
2. Update the example configuration file (usually in config/initializers/apipie.rb in the consuming app) (lib/apipie/configuration.rb)
3. Reference the configuration value in the appropriate layer (e.g., application.rb for global state) (lib/apipie/application.rb)

Customize documentation UI or add a new view template

1. Create or modify an ERB template in the apipie/apipies views directory (app/views/apipie/apipies/)
2. Update or add a corresponding route and controller action in apipies_controller.rb (app/controllers/apipie/apipies_controller.rb)
3. Add helper methods in the apipie_helper.rb if rendering logic is needed (app/helpers/apipie_helper.rb)
4. Add CSS styles to the stylesheet or JavaScript behavior to apipie.js (app/public/apipie/stylesheets/application.css)

Export API documentation to OpenAPI/Swagger format

1. Configure Apipie to enable Swagger generation in config/initializers/apipie.rb (lib/apipie/configuration.rb)
2. Run the Swagger generator task to convert all documented endpoints to OpenAPI spec (lib/apipie/generator/generator.rb)
3. The generator uses method_description.rb to transform each endpoint's DSL into OpenAPI operation objects (lib/apipie/generator/swagger/method_description.rb)
4. Parameters and responses are converted via param_description/builder.rb and response_service.rb (lib/apipie/generator/swagger/method_description/parameters_service.rb)

• Ruby on Rails Engine — Seamless integration with existing Rails apps; automatically mounts routes, views, and assets
• DSL-based annotation — Developers document code inline in controllers using familiar Ruby syntax; no external YAML/JSON files needed
• OpenAPI/Swagger export — Enables tool ecosystem support (Postman, Swagger UI, code generators); bridges Apipie to industry standards
• ERB templates + Bootstrap CSS — Provides a responsive, self-hosted documentation UI without external dependencies; easily customizable

• Runtime documentation extraction vs. build-time code generation

  • Why: Keeps documentation in sync with live code; developers see changes immediately without rebuild
  • Consequence: Slight runtime overhead on first documentation request; must cache or precompute for production

• Monolithic gem vs. modular plugins

  • Why: Single installation and configuration; users get DSL, UI, and Swagger generation out-of-the-box
  • Consequence: Larger gemfile footprint; some features (Swagger) always compiled even if unused

• Rails-only design

  • Why: Deep integration with Rails conventions and routing; simple setup for Rails projects
  • Consequence: Cannot be used in non-Rails Ruby applications; requires Rails engine compatibility

• Real-time API mocking or request simulation
• Client SDK generation from Apipie documentation
• API gateway or reverse proxy functionality
• Authentication/authorization enforcement (documents existing auth, does not implement it)
• Database schema documentation (focuses on HTTP API endpoints only)
• GraphQL support (REST/HTTP-only)

1. Rails engine mounting: Apipie must be mounted in config/routes.rb (likely mount Apipie::Engine => '/apipie') — if missing, /apipie won't load. 2. Documentation refresh: In development, changes to DSL annotations are picked up on page reload, but caching may hide changes in production; ensure config.cache_classes = false in dev. 3. Gem version locks: Check apipie-rails.gemspec for Rails version constraints (e.g., >= 4.2); using an older/newer Rails may break. 4. Asset precompilation: Bundled assets (Bootstrap, jQuery) are served from app/public/apipie/; ensure rake assets:precompile includes them in production. 5. DSL method availability: The DSL keywords (api, param, error, deprecated, etc.) are only available in controllers that include the Apipie module — check if your controller inherits from ApplicationController correctly.

• Rails Engine — Apipie is packaged as a mountable Rails engine (see apipie-rails.gemspec and app/controllers/apipie/), allowing it to be dropped into any Rails app without modifying core framework code; understanding engines is critical to extend or debug Apipie
• Ruby DSL (Domain-Specific Language) — Apipie's core value is its Ruby DSL (api, param, error keywords in controller methods); learning how this metaprogramming works teaches you to extend the DSL for custom documentation needs
• Introspection and Reflection — Apipie extracts documentation at Rails boot time by reflecting on controller method annotations; this avoids runtime parsing and enables static analysis of your API
• Content Negotiation (Accept Headers) — Apipie serves HTML docs and JSON API from the same routes (e.g., /apipie returns HTML, /apipie.json returns JSON) using Rails content_type negotiation; essential for building multi-format API frontends
• Decorator Pattern — The DSL uses decorators (DSL helper methods that augment controller actions with metadata) rather than inheritance; understanding this pattern helps you extend Apipie without forking
• Asset Pipeline (Rails) — Apipie's static assets (CSS, JS, images in app/public/apipie/) must be precompiled and served correctly in production; mishandling this is a common deployment gotcha
• API Versioning via Documentation — Apipie supports documenting multiple API versions separately (checksum endpoint, version parameter in views); critical for maintaining backwards compatibility while evolving your API

• rswag/rswag — OpenAPI/Swagger documentation for Rails APIs; similar goal (live docs) but uses OpenAPI spec format instead of Ruby DSL
• ruby-grape/grape-swagger — Swagger/OpenAPI generator for Grape (Rack-based API framework); alternative to Apipie if using Grape instead of Rails controllers
• Apipie/apipie-demo — Official demo Rails app showing Apipie in action with full examples; essential reference for learning the DSL and features
• rails/rails — Core Rails framework; Apipie is a Rails engine and depends on ActionController, routing, and view rendering
• thoughtbot/factory_bot — Test fixture/factory library commonly used in Apipie test suites to generate example objects for documentation

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive JavaScript unit tests for app/public/apipie/javascripts/apipie.js

The main apipie.js file is a critical component for the interactive API documentation UI (handling collapsing, prettifying, etc.), but there are no visible test files for it in the repo structure. Adding Jest or Mocha tests would improve reliability and prevent regressions when bundled dependencies (bootstrap.js, prettify.js, jquery.js) are updated.

• [ ] Create spec/javascript or test/javascript directory structure with test configuration
• [ ] Write unit tests for core apipie.js functions (DOM manipulation, event handlers, initialization logic)
• [ ] Add test coverage for integration with bundled libraries in app/public/apipie/javascripts/bundled/
• [ ] Integrate JavaScript tests into .github/workflows/build.yml CI pipeline

Add end-to-end tests for view rendering and HTML output validation

The app/views/apipie/apipies/ directory contains 10+ ERB templates that generate the API documentation UI. There's no clear evidence of integration tests validating that these templates render correctly with various parameter combinations, i18n locales, and edge cases. This is critical for UX quality.

• [ ] Create spec/views/apipie/ directory with RSpec view specs
• [ ] Add tests for each template in app/views/apipie/apipies/ (_params.html.erb, _method_detail.erb, index.html.erb, etc.)
• [ ] Test i18n rendering across config/locales/ files (de.yml, ja.yml, pt-BR.yml, etc.)
• [ ] Add tests for deprecation, errors, and metadata display partials

Create GitHub Actions workflow for automated dependency updates with Dependabot

The gemfiles/ directory and bundled JavaScript libraries (bootstrap.js, jquery.js, etc.) in app/public/apipie/javascripts/bundled/ suggest multiple dependency sources. Currently only .github/workflows/build.yml, rubocop.yml, and rubocop-challenger.yml exist. A Dependabot workflow would automatically detect and test gem/npm updates, reducing maintenance burden.

• [ ] Add .github/dependabot.yml configuration for Ruby gems and JavaScript dependencies
• [ ] Configure auto-merge for patch/minor version updates after CI passes
• [ ] Document dependency update process in CONTRIBUTING.md or README.md
• [ ] Test that existing CI pipeline (build.yml) properly validates dependency updates

• Add unit tests for app/views/apipie/apipies/_errors.html.erb error rendering. Currently no visible test coverage for the error display template; create a spec in spec/views/ to verify error codes, descriptions, and styling are rendered correctly.: easy: Safe, isolated file; teaches Rails view testing and Apipie's error model
• Document the DSL by adding code comments and a usage guide for lib/apipie/dsl_helper.rb (inferred file). The README shows api :GET and param examples but lacks formal DSL reference docs. Create a docs/DSL_REFERENCE.md with method signatures and real examples.: medium: Improves onboarding; no coding required, pure documentation
• Fix missing <title> tag in app/views/apipie/apipies/index.html.erb. Currently the HTML head likely has no page title, making browser tabs unclear. Add dynamic title generation based on API name.: easy: Quick UX win; teaches ERB templating and Apipie configuration
• Add integration tests for the JSON API endpoints (/apipie.json and checksum endpoint). The view apipie_checksum.json.erb and API responses are not tested. Create spec/requests/apipie_json_api_spec.rb to verify JSON structure, versioning, and response codes.: medium: Covers a critical API surface; teaches Rails request specs and JSON validation

The Apipie-rails

• High · Potential XSS Vulnerability in View Templates — app/views/apipie/apipies/*.erb files. Multiple ERB template files (app/views/apipie/apipies/) are present in the codebase. Without examining the actual template content, there is a risk of Cross-Site Scripting (XSS) if user-supplied API documentation, parameters, or method descriptions are rendered without proper escaping. The tool processes and displays API documentation which could contain malicious content. Fix: Audit all ERB templates to ensure user-supplied content is properly escaped using <%= %> instead of <%== %>. Implement Content Security Policy (CSP) headers. Use Rails' built-in XSS protection with config.action_view.default_form_builder and auto-escaping enabled.
• High · Bundled Outdated Third-Party JavaScript Libraries — app/public/apipie/javascripts/bundled/. The codebase includes bundled JavaScript libraries (jQuery, Bootstrap, Prettify) in app/public/apipie/javascripts/bundled/. These bundled versions are likely outdated and may contain known vulnerabilities. Bundled dependencies are not automatically updated by package managers. Fix: Replace bundled libraries with npm/yarn dependencies and use a package manager for updates. Implement security scanning with tools like npm audit or bundler-audit. Regularly update dependencies to patch known CVEs. Consider using a CDN for well-maintained libraries.
• Medium · Missing Dependency Manifest — Gemfile, apipie-rails.gemspec. No Gemfile content or package.json was provided for analysis. The project appears to be a Rails gem but the actual runtime and development dependencies are not visible. This prevents assessment of known vulnerable dependencies. Fix: Run 'bundle audit' regularly to check for vulnerable gems. Implement automated dependency scanning in CI/CD pipeline (e.g., Dependabot, Snyk). Review gemspec for overly permissive version constraints (e.g., avoid '>= 1.0' without upper bounds).
• Medium · Potential Information Disclosure via API Documentation — app/controllers/apipie/apipies_controller.rb. The Apipie tool exposes API documentation publicly through app/controllers/apipie/apipies_controller.rb. This could inadvertently expose sensitive API structure, parameter details, or internal implementation details to unauthorized users if access controls are not properly configured. Fix: Implement authentication/authorization checks in ApipiesController to restrict documentation access. Use Apipie's built-in access control configuration. Consider disabling API documentation in production or restricting it to authenticated users. Audit what information is exposed in the documentation.
• Medium · Unsafe Static File Serving — app/public/apipie/stylesheets/, app/public/apipie/javascripts/. The app/public/apipie directory contains CSS and JavaScript files that are served statically. Without proper content delivery configuration, these files could be vulnerable to MIME-type attacks or may lack security headers. Fix: Configure proper MIME types for all static assets. Implement security headers (X-Content-Type-Options: nosniff, Content-Security-Policy). Use asset fingerprinting in Rails (config.assets.digest = true). Serve assets through a CDN with security headers.
• Low · No Evidence of Security Testing Configuration — .rubocop.yml, build configuration. While rubocop and rspec are configured (.rspec, .rubocop.yml), there is no visible evidence of security-focused testing tools like Brakeman (Rails security scanner) or OWASP ZAP integration. Fix: Integrate Brakeman for static security analysis in CI/CD pipeline. Add security-focused RSpec tests. Consider SAST tools in GitHub Actions workflow (.github/workflows/build.yml). Implement regular penetration testing for the documentation interface.
• Low · Missing SECURITY.md or Security Policy — Repository root. No SECURITY.md or security policy file is present to guide users on reporting security vulnerabilities responsibly. Fix: Create a SECURITY.md file with instructions for responsible disclosure. Include contact information for security reports. Reference the project's security patch process and timeline for responses.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.