grape-swagger-rails: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Gem Does

grape-swagger-rails is a Rails Engine gem that mounts a Swagger UI interface for APIs documented with the grape-swagger gem. It provides a single mountable engine that renders Swagger UI v5 with configurable authentication, theming, and authorization hooks.

Commands

bundle exec rake            # Run full suite: RuboCop + RSpec (default)
bundle exec rake spec       # Run all RSpec tests only
bundle exec rake rubocop    # Run RuboCop linting only
bundle exec rspec spec/features/swagger_spec.rb  # Run a single spec file

yarn build:frontend         # tsc → index.js, then esbuild → index.min.js (+ .map)
yarn build:frontend:js      # Just tsc (readable bundle)
yarn build:frontend:min     # Just esbuild (minified bundle, consumes index.js)
yarn typecheck              # Type-check TypeScript without emitting

bundle exec rake swagger_ui:dist:update          # Update bundled Swagger UI assets
SWAGGER_UI_VERSION=v5.32.5 bundle exec rake swagger_ui:dist:update  # Pin to a version

Tests use Capybara + Selenium with Firefox. Firefox and geckodriver must be installed locally. On macOS, xvfb is not needed (unlike CI). Tests launch a real browser to validate UI behavior.

After editing TypeScript, run yarn build:frontend before running specs — the specs exercise app/assets/javascripts/grape_swagger_rails/index.js, which is the compiled output. Never edit the compiled JS directly. The build also emits index.min.js (+ sourcemap); the view picks the minified bundle in production (Rails.env.production?) via grape_swagger_rails_runtime_asset and the readable one everywhere else.

Architecture

The gem has minimal moving parts:

• lib/grape-swagger-rails.rb — Defines GrapeSwaggerRails.options as an OpenStruct. All configuration lives here (URL, auth type, headers, theme, before_action proc, etc.).
• lib/grape-swagger-rails/engine.rb — Rails Engine. Configures asset precompilation for both Sprockets and Propshaft pipelines.
• app/controllers/grape_swagger_rails/application_controller.rb — Single index action. Runs options.before_action_proc in controller context for authorization.
• app/views/grape_swagger_rails/application/index.html.haml — The entire UI. Serializes GrapeSwaggerRails.options as JSON into data-swagger-options, then JavaScript parses it to initialize SwaggerUIBundle. Handles theme toggling and auth injection via Swagger UI's requestInterceptor.
• frontend/grape_swagger_rails/index.ts — TypeScript source for the browser runtime. tsc compiles it to app/assets/javascripts/grape_swagger_rails/index.js (readable, ES5); esbuild then minifies that into index.min.js (+ .map). Both files are checked in so they ship with the gem. The TypeScript interface SwaggerPageOptions is the authoritative schema for options consumed by JS.
• config/routes.rb — Single root route → ApplicationController#index.
• lib/tasks/swagger_ui.rake — Rake task that clones swagger-api/swagger-ui and copies dist files into app/assets/.