diff --git a/.okf/config/appender.md b/.okf/config/appender.md new file mode 100644 index 0000000..22d6d01 --- /dev/null +++ b/.okf/config/appender.md @@ -0,0 +1,40 @@ +--- +type: Component +title: Config::Appender +description: Append-only merge of a freshly generated config into the existing YAML, where existing entries always win. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/config/appender.rb +tags: [append-only, yaml] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: appender.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/config/appender.rb + - id: tests + title: test/config/appender_test.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/test/config/appender_test.rb +--- + +# Rules + +- Endpoint identity: `"#{method} #{path}"`. +- Existing endpoints are kept **verbatim**; generated ones only appended when their identity is new. +- New sections appended at the end; existing section metadata (name, description, show) untouched. +- `general_configurations`: `generated.merge(existing)` — existing keys win, missing keys filled in, + so a new gem option never forces a manual edit.[^src] +- `changes?`/`diff` drive the generator's `unchanged` vs `updated (+N section(s), +M endpoint(s))` status. + +Why: [append-only merge](/decisions/append-only-merge.md). + +# Consequences + +- Removed routes are **never** pruned from the YAML. +- Changing a route's path or verb creates a new endpoint; the old one stays (user deletes it). +- Moving a route to a different controller key appends it to the new section even if the identical + identity exists under the old one (identity is checked per section).[^src] + +# Guardrail + +Any change here must keep `appender_test.rb` covering: user edits survive, existing +`general_configurations` never overwritten (new keys added), header comments preserved.[^tests] diff --git a/.okf/config/builder.md b/.okf/config/builder.md new file mode 100644 index 0000000..515f863 --- /dev/null +++ b/.okf/config/builder.md @@ -0,0 +1,31 @@ +--- +type: Component +title: Config::Builder +description: Turns route hashes plus inferred bodies into the full config hash written to the YAML. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/config/builder.rb +tags: [yaml] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: builder.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/config/builder.rb +--- + +# Overview + +Groups routes by controller into sections, builds each endpoint (method, path, name, description, show, +params, body, responses).[^src] Output shape is the [YAML config format](/config/yaml-format.md). + +# Non-obvious + +- **Endpoint names** come from `ACTION_VERB_PHRASE` + singular/plural of the last controller segment + (`index` → plural, others singular). Custom actions are humanized. +- **Path param typing**: `id` or `*_id` → `integer`, else `string`; always `in: path`, `required: true`.[^src] +- **Always emits `responses["200"]`** with `example: ""` — this has a rendering side-effect, see + [scaffolded response example is always {}](/pitfalls/scaffold-response-example-empty.md). +- Verbose mode adds empty arrays (`params: []`, `body: []`) purely for discoverability + ([pragmatic default YAML](/decisions/pragmatic-default-yaml.md)). +- `DEFAULT_GENERAL` and `verbose_field_defaults` are duplicated elsewhere — see + [duplicated defaults](/pitfalls/duplicated-defaults.md). diff --git a/.okf/config/configuration.md b/.okf/config/configuration.md new file mode 100644 index 0000000..66d2ef2 --- /dev/null +++ b/.okf/config/configuration.md @@ -0,0 +1,39 @@ +--- +type: Component +title: RailsApiDocs::Configuration +description: Global settings object — paths, dev mount toggle, route filters, api_only and verbose_yaml defaults. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/configuration.rb +tags: [filtering, cli] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: configuration.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/configuration.rb + - id: gen + title: InitGenerator#scoped_config + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/generators/rails-api-docs/init/init_generator.rb +--- + +# Schema + +| Setting | Default | Notes | +|---------|---------|-------| +| `config_path` | `config/rails-api-docs.yml` | relative to `Rails.root` | +| `output_path` | `public/api-docs.html` | build target | +| `mount_path` | `/rails/api-docs` | [dev mount](/distribution/dev-mount.md) | +| `mount_in_development` | `true` | | +| `ignored_path_prefixes` / `ignored_controllers` / `ignored_actions` | `[]` | blacklists | +| `only_controllers` | `[]` | whitelist; empty = inactive | +| `api_only` | `false` | see [JsonRouteDetector](/inspection/json-route-detector.md) | +| `verbose_yaml` | `false` | see [pragmatic default YAML](/decisions/pragmatic-default-yaml.md) | +| `route_source` | lazy `Rails.application.routes` | injectable for tests | + +[^src] + +# Precedence + +CLI flags win over this object. The generator builds a **per-run dup** (`scoped_config`) and overlays +CLI values on it, so a run never mutates global state.[^gen] See [generators](/distribution/generators.md) +and [nil-default CLI flags](/decisions/nil-default-cli-flags.md). diff --git a/.okf/config/controller-matching.md b/.okf/config/controller-matching.md new file mode 100644 index 0000000..f770af3 --- /dev/null +++ b/.okf/config/controller-matching.md @@ -0,0 +1,29 @@ +--- +type: Component +title: Controller matching rule +description: The shared rule used by ignored_controllers and only_controllers — regexp, exact path, or boundary-aware suffix. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/inspectors/route_inspector.rb +tags: [filtering] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: RouteInspector#controller_matches? + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/inspectors/route_inspector.rb +--- + +# Rule + +| Pattern | Match | +|---------|-------| +| `Regexp` | `Regexp#match?` | +| String with `/` | exact (`api/v1/users` matches only itself) | +| String without `/` | equal **or** ends with `/` (`users` ⇒ `users`, `api/v1/users`; not `super_users`) | + +[^src] + +Both lists share this one method so they stay symmetric. Blacklist wins when both match. +Before v0.1.0 shipped, `ignored_controllers` was exact-match; it was switched to this rule with no migration +impact because nothing had been released. Used by [RouteInspector](/inspection/route-inspector.md), +configured via [Configuration](/config/configuration.md). diff --git a/.okf/config/index.md b/.okf/config/index.md new file mode 100644 index 0000000..03123b8 --- /dev/null +++ b/.okf/config/index.md @@ -0,0 +1,8 @@ +# Config + +* [YAML config format](yaml-format.md) - The hand-edited contract between the scaffold side and the render side. +* [Config::Builder](builder.md) - Turns route hashes plus inferred bodies into the full config hash. +* [Config::Appender](appender.md) - Append-only merge where existing entries always win. +* [Config::Loader](loader.md) - Safe YAML loading plus header-comment preservation. +* [RailsApiDocs::Configuration](configuration.md) - Global settings: paths, dev mount, filters, api_only, verbose_yaml. +* [Controller matching rule](controller-matching.md) - Shared rule for ignored_controllers and only_controllers. diff --git a/.okf/config/loader.md b/.okf/config/loader.md new file mode 100644 index 0000000..20960dd --- /dev/null +++ b/.okf/config/loader.md @@ -0,0 +1,22 @@ +--- +type: Component +title: Config::Loader +description: Safe YAML loading plus extraction of the leading comment header so it survives re-runs. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/config/loader.rb +tags: [yaml] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: loader.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/config/loader.rb +--- + +# Overview + +- `load` uses `YAML.safe_load` permitting only `Symbol`, `Date`, `Time`; a missing file returns `{}`.[^src] +- `header` returns the leading run of `#` and blank lines. The generator re-prepends it after + `YAML.dump`, which is the **only** reason user comments at the top survive. Comments anywhere else are lost — + see [known limitations](/operations/known-limitations.md). +- Used by both halves of the [pipeline](/overview/pipeline.md): generator (merge) and renderer (display). diff --git a/.okf/config/yaml-format.md b/.okf/config/yaml-format.md new file mode 100644 index 0000000..0de399b --- /dev/null +++ b/.okf/config/yaml-format.md @@ -0,0 +1,40 @@ +--- +type: Data Format +title: YAML config format (config/rails-api-docs.yml) +description: The hand-edited contract between the scaffold side and the render side — general_configurations plus sections keyed by controller. +tags: [yaml, append-only] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: readme + title: README — YAML structure / complete reference + resource: https://github.com/jacksonpires/rails-api-docs#yaml-structure + - id: renderer + title: Doc::Renderer (consumer of every key) + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/doc/renderer.rb +--- + +# Overview + +The only file the user maintains by hand; the HTML is always derived from it. +The full key-by-key reference is in the README[^readme] — this concept records the **contract rules**, +not the key list. + +# Schema (shape) + +| Path | Notes | +|------|-------| +| `general_configurations` | title, base_url, 3 colors, font_family, show_curl, show_examples. Missing keys are filled from renderer defaults at render time and from builder defaults on re-scaffold. | +| `sections.` | `name`, `description`, `show`, `endpoints[]`. Key is the stable controller path. | +| `endpoints[]` | Only `method` + `path` required. Identity = `"#{method} #{path}"`. | +| field arrays | `params`, `body`, `headers`, `responses..headers`, `responses..schema` — all rendered by one helper. | + +# Contract rules + +- `show: false` hides a section or endpoint at render time; a section with zero visible endpoints disappears.[^renderer] +- The renderer must tolerate **any** missing key — users delete freely. +- Delete an endpoint/section from the YAML to have the next `:update` regenerate it + ([Config::Appender](/config/appender.md)). +- Inline comments are lost on re-dump; the leading header block survives ([Config::Loader](/config/loader.md)). +- Example values: see [field example is the source of truth](/decisions/field-example-source-of-truth.md). diff --git a/.okf/decisions/api-only-strict.md b/.okf/decisions/api-only-strict.md new file mode 100644 index 0000000..472063d --- /dev/null +++ b/.okf/decisions/api-only-strict.md @@ -0,0 +1,25 @@ +--- +type: Decision +title: --api-only is strict on unknowns +description: When JSON-ness can't be proven statically the route is excluded, keeping the YAML clean in mixed HTML/API apps. +tags: [api-only, filtering] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: readme + title: README — Scaffolding only JSON-returning routes + resource: https://github.com/jacksonpires/rails-api-docs#scaffolding-only-json-returning-routes---api-only +--- + +# Decision + +Missing controller file or unresolvable parent ⇒ `:unknown` ⇒ **not** API. Only proven JSON is kept.[^readme] + +# Why + +Apps mixing Devise, RailsAdmin or HTML controllers would otherwise flood the YAML. A false negative costs one +manual entry; a false positive costs noise in every re-run (append-only never removes it — see +[append-only merge](/decisions/append-only-merge.md)). + +Implemented by [JsonRouteDetector](/inspection/json-route-detector.md). diff --git a/.okf/decisions/append-only-merge.md b/.okf/decisions/append-only-merge.md new file mode 100644 index 0000000..3da4996 --- /dev/null +++ b/.okf/decisions/append-only-merge.md @@ -0,0 +1,29 @@ +--- +type: Decision +title: Append-only merge — user edits are sacred +description: Re-running the generator only adds new routes and missing config keys; it never modifies or prunes existing YAML entries. +tags: [append-only, yaml] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: claude + title: CLAUDE.md — Sensitive areas / Config::Appender + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/CLAUDE.md + - id: readme + title: README — Updating the YAML + resource: https://github.com/jacksonpires/rails-api-docs#updating-the-yaml +--- + +# Decision + +The YAML is the user's document; the code inspection is only a first draft. So on re-run, +**existing fields always win** and nothing is removed.[^claude] + +# Tradeoffs accepted + +- Stale endpoints (removed routes) accumulate until deleted by hand. +- Regenerating one endpoint means deleting it from the YAML and re-running `:update`.[^readme] +- Inline comments are lost because the file is re-dumped with `YAML.dump` — only the header is re-attached. + +Implemented by [Config::Appender](/config/appender.md) and [Config::Loader](/config/loader.md). diff --git a/.okf/decisions/field-example-source-of-truth.md b/.okf/decisions/field-example-source-of-truth.md new file mode 100644 index 0000000..dc1a043 --- /dev/null +++ b/.okf/decisions/field-example-source-of-truth.md @@ -0,0 +1,22 @@ +--- +type: Decision +title: field example is the source of truth for sample values +description: Every place that needs a sample value prefers the field's own example and falls back to SampleValue.for(type). +tags: [sample-values] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: claude + title: CLAUDE.md — field["example"] is the single source of truth + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/CLAUDE.md +--- + +# Decision + +Precedence everywhere: **user `example` → `SampleValue.for(type)`**.[^claude] The scaffold seeds `example` +on every inferred field, so the fallback is mostly for hand-added fields without one. + +Applies in [CurlRenderer](/rendering/curl-renderer.md) (`--data`, path params, headers) and in +[Doc::Renderer](/rendering/renderer.md)'s synthesized response. Any new placeholder site must follow the same +order and call [SampleValue](/rendering/sample-value.md). diff --git a/.okf/decisions/index.md b/.okf/decisions/index.md new file mode 100644 index 0000000..8ca2e0a --- /dev/null +++ b/.okf/decisions/index.md @@ -0,0 +1,10 @@ +# Decisions + +* [Append-only merge](append-only-merge.md) - Re-runs only add; existing YAML entries are never modified or pruned. +* [Static analysis with Prism](static-analysis-with-prism.md) - Parse controller source instead of loading classes. +* [--api-only is strict](api-only-strict.md) - Unprovable routes are excluded. +* [Self-contained HTML](self-contained-html.md) - One file, everything inlined. +* [Pragmatic default YAML](pragmatic-default-yaml.md) - Commonly edited keys by default; --verbose-yaml for everything. +* [Field example is the source of truth](field-example-source-of-truth.md) - User example first, SampleValue fallback. +* [init and update are one generator](init-update-alias.md) - Namespace-only subclass. +* [CLI flags default to nil](nil-default-cli-flags.md) - Distinguishes omitted from explicitly off. diff --git a/.okf/decisions/init-update-alias.md b/.okf/decisions/init-update-alias.md new file mode 100644 index 0000000..bb46a1f --- /dev/null +++ b/.okf/decisions/init-update-alias.md @@ -0,0 +1,22 @@ +--- +type: Decision +title: init and update are one generator +description: rails-api-docs:update is a namespace-only subclass of :init; the code self-detects create vs append. +tags: [cli, append-only] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: update + title: update_generator.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/generators/rails-api-docs/update/update_generator.rb +--- + +# Decision + +Two names for readability (first run vs re-run), one implementation.[^update] Running `:init` on an existing +YAML is safe — it appends, exactly like `:update`. + +# Rule for contributors + +Add flags and logic to `InitGenerator` only. See [generators](/distribution/generators.md). diff --git a/.okf/decisions/nil-default-cli-flags.md b/.okf/decisions/nil-default-cli-flags.md new file mode 100644 index 0000000..e09a87f --- /dev/null +++ b/.okf/decisions/nil-default-cli-flags.md @@ -0,0 +1,23 @@ +--- +type: Decision +title: CLI boolean flags default to nil +description: Generator class_options default to nil so "flag omitted" falls back to Configuration while --no-flag can override it. +tags: [cli] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: init + title: InitGenerator#api_only? / #verbose_yaml? + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/generators/rails-api-docs/init/init_generator.rb +--- + +# Decision + +`class_option :api_only, type: :boolean, default: nil` (same for `verbose_yaml`, `only_controllers`). +`nil` → use [Configuration](/config/configuration.md); `true`/`false` → CLI wins.[^init] + +# Why + +With `default: false` there is no way to tell "not passed" from `--no-api-only`, so a persistent +`api_only = true` could never be overridden for a single run. Used by [generators](/distribution/generators.md). diff --git a/.okf/decisions/pragmatic-default-yaml.md b/.okf/decisions/pragmatic-default-yaml.md new file mode 100644 index 0000000..512e1b0 --- /dev/null +++ b/.okf/decisions/pragmatic-default-yaml.md @@ -0,0 +1,26 @@ +--- +type: Decision +title: Pragmatic default YAML, verbose opt-in +description: The scaffold emits only commonly edited keys by default; --verbose-yaml emits every key for discoverability at ~10x size. +tags: [yaml, cli] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: claude + title: CLAUDE.md — Pragmatic vs verbose YAML scaffold + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/CLAUDE.md +--- + +# Decision + +Default: `description` + `example` on every inferred field and a minimal `responses["200"]` stub. +Verbose: every field/endpoint key with defaults, roughly 10× more lines per endpoint.[^claude] + +# Why + +Users edit values far more often than they discover keys; a short file is easier to maintain under +[append-only merge](/decisions/append-only-merge.md). Verbose exists for first-time exploration. + +Verbose defaults are produced by methods returning fresh objects — see [YAML anchors](/pitfalls/yaml-anchors.md). +Implemented in [Config::Builder](/config/builder.md) and [BodyInferrer](/inspection/body-inferrer.md). diff --git a/.okf/decisions/self-contained-html.md b/.okf/decisions/self-contained-html.md new file mode 100644 index 0000000..9d0b151 --- /dev/null +++ b/.okf/decisions/self-contained-html.md @@ -0,0 +1,24 @@ +--- +type: Decision +title: Self-contained HTML output +description: The output is one HTML file with all CSS and JS inlined, served live in dev and statically in production. +tags: [html] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: readme + title: README — intro + resource: https://github.com/jacksonpires/rails-api-docs#rails-api-docs +--- + +# Decision + +No asset pipeline, no CDN, no JS runtime: one file droppable on any static host.[^readme] The gem is a +`development`-group dependency; production only needs the built file. + +# Consequences + +- All styling and behaviour live in one ERB ([HTML template](/rendering/html-template.md)); it is large by design. +- Theming is done through CSS variables fed from `general_configurations`, not separate stylesheets. +- Two delivery paths share one renderer: [dev mount](/distribution/dev-mount.md) and [build task](/distribution/build-task.md). diff --git a/.okf/decisions/static-analysis-with-prism.md b/.okf/decisions/static-analysis-with-prism.md new file mode 100644 index 0000000..db2b262 --- /dev/null +++ b/.okf/decisions/static-analysis-with-prism.md @@ -0,0 +1,31 @@ +--- +type: Decision +title: Static analysis with Prism instead of loading controllers +description: Controllers are parsed as source with Prism rather than introspected at runtime, trading precision for zero side effects. +tags: [prism] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: gemspec + title: rails-api-docs.gemspec (prism >= 0.24 dependency) + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/rails-api-docs.gemspec +--- + +# Decision + +Permits and JSON-ness are read from the controller **source file** via Prism (a runtime dependency, +`prism >= 0.24`[^gemspec]), never by loading/instantiating controller classes. + +# Why + +- No side effects from loading app code (before_actions, constants, DB connections). +- Works even when a controller can't be loaded in the generator's context. +- Prism is the stock Ruby parser going forward, so the AST API is stable across Ruby 3.1–4.0. + +# Cost + +Anything dynamic is invisible: splat permits, helpers, included modules, metaprogrammed renders. +The gem prefers **missing a field** (user adds it) over **inventing one**. See +[ControllerInspector](/inspection/controller-inspector.md), [JsonRouteDetector](/inspection/json-route-detector.md), +[known limitations](/operations/known-limitations.md). diff --git a/.okf/distribution/build-task.md b/.okf/distribution/build-task.md new file mode 100644 index 0000000..123dd3a --- /dev/null +++ b/.okf/distribution/build-task.md @@ -0,0 +1,27 @@ +--- +type: Component +title: rake rails-api-docs:build +description: Writes the self-contained HTML (default public/api-docs.html) from the YAML, with CONFIG= and OUTPUT= overrides. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/tasks/rails-api-docs.rake +tags: [html, cli] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: task + title: rails-api-docs.rake + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/tasks/rails-api-docs.rake + - id: fb + title: doc/file_builder.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/doc/file_builder.rb +--- + +# Overview + +Thin rake body over `Doc::FileBuilder`, extracted so the build flow is unit-testable.[^task] +`ENV["CONFIG"]` / `ENV["OUTPUT"]` override [Configuration](/config/configuration.md) paths (both resolved +against `Rails.root`). Missing YAML raises `MissingConfigError` → message on stderr, `exit 1`. +FileBuilder creates the output directory if needed.[^fb] + +Both the build and the [dev mount](/distribution/dev-mount.md) render through the same +[Doc::Renderer](/rendering/renderer.md), so the dev view is exactly what ships. diff --git a/.okf/distribution/dev-mount.md b/.okf/distribution/dev-mount.md new file mode 100644 index 0000000..6fb8d18 --- /dev/null +++ b/.okf/distribution/dev-mount.md @@ -0,0 +1,36 @@ +--- +type: Component +title: Dev mount (/rails/api-docs) +description: Engine route appended in development that re-renders the docs from the YAML on every request, or shows a setup page. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/engine.rb +tags: [rails-engine, html] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: engine + title: engine.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/engine.rb + - id: responder + title: doc/responder.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/doc/responder.rb + - id: controller + title: app/controllers/rails_api_docs/docs_controller.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/app/controllers/rails_api_docs/docs_controller.rb +--- + +# Overview + +The `rails_api_docs.mount` initializer **appends** a mount at `mount_path` only when +`mount_in_development && Rails.env.development?`.[^engine] Production never registers it; it serves the +file produced by the [build task](/distribution/build-task.md). + +# Pieces + +- `DocsController < ActionController::Base` with `layout false` (page is a full ``), delegates to + `Doc::Responder`.[^controller] +- `Doc::Responder` is pure Ruby so the decision (YAML present → 200 render; missing → 404 setup page telling + you to run `rails g rails-api-docs:init`) is unit-testable without booting Rails.[^responder] +- No caching: each request re-reads the YAML, which is the whole point of the edit-and-refresh loop. +- `rake_tasks` / `generators` blocks must stay at Engine class-body level — see + [engine macros pitfall](/pitfalls/engine-class-macros.md). diff --git a/.okf/distribution/generators.md b/.okf/distribution/generators.md new file mode 100644 index 0000000..614db3a --- /dev/null +++ b/.okf/distribution/generators.md @@ -0,0 +1,39 @@ +--- +type: Component +title: init / update generators +description: rails g rails-api-docs:init and :update — one implementation that scaffolds fresh or appends, with CLI filter flags. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/generators/rails-api-docs/init/init_generator.rb +tags: [cli, append-only, filtering] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: init + title: init_generator.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/generators/rails-api-docs/init/init_generator.rb + - id: update + title: update_generator.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/generators/rails-api-docs/update/update_generator.rb +--- + +# Overview + +`UpdateGenerator < InitGenerator` and only overrides `namespace` + `desc`; Thor carries `class_option`s to +subclasses, so new flags/logic go in `InitGenerator` only.[^update] Behaviour self-detects: file missing → fresh +scaffold with header; file present → [Config::Appender](/config/appender.md) merge. See +[init and update are one generator](/decisions/init-update-alias.md). + +# Flags + +| Flag | Effect | +|------|--------| +| `--api-only` / `--no-api-only` | filter via [JsonRouteDetector](/inspection/json-route-detector.md) | +| `--only-controllers` | whitelist; accepts `a b`, `a,b`, `[a,b]`, `[ a , b ]` | +| `--verbose-yaml` | every key with defaults | + +[^init] + +- `namespace "rails-api-docs:init"` is **forced**; without it Rails infers `rails_api_docs:init` from the module. +- All flags default to `nil` — see [nil-default CLI flags](/decisions/nil-default-cli-flags.md). +- Repeating `--only-controllers` does **not** merge — Thor keeps the last occurrence. +- Filtering is scaffold-time only: re-running with `--api-only` never removes HTML routes already in the YAML. diff --git a/.okf/distribution/index.md b/.okf/distribution/index.md new file mode 100644 index 0000000..174c8a0 --- /dev/null +++ b/.okf/distribution/index.md @@ -0,0 +1,5 @@ +# Distribution + +* [init / update generators](generators.md) - One implementation that scaffolds fresh or appends, with CLI filter flags. +* [Dev mount](dev-mount.md) - /rails/api-docs re-renders from the YAML on every request in development. +* [Build task](build-task.md) - rake rails-api-docs:build writes the self-contained HTML. diff --git a/.okf/index.md b/.okf/index.md new file mode 100644 index 0000000..9fec969 --- /dev/null +++ b/.okf/index.md @@ -0,0 +1,18 @@ +--- +okf_version: "0.2" +--- + +# rails-api-docs knowledge bundle + +Knowledge, decisions and documentation for the `rails-api-docs` gem. Start with the [pipeline](overview/pipeline.md). + +# Areas + +* [Overview](overview/) - End-to-end pipeline and glossary. +* [Inspection](inspection/) - Route, controller (Prism), schema and JSON-route inspectors that feed the scaffold. +* [Config](config/) - The YAML contract, how it is built, merged append-only and loaded; global configuration and filters. +* [Rendering](rendering/) - YAML → self-contained HTML: renderer, template, cURL, sample values. +* [Distribution](distribution/) - How users run it: generators, dev mount, build task. +* [Decisions](decisions/) - Why the gem works the way it does. +* [Pitfalls](pitfalls/) - Traps that already bit (or will bite) contributors. +* [Operations](operations/) - Testing, releasing, known limitations. diff --git a/.okf/inspection/body-inferrer.md b/.okf/inspection/body-inferrer.md new file mode 100644 index 0000000..ec613f9 --- /dev/null +++ b/.okf/inspection/body-inferrer.md @@ -0,0 +1,31 @@ +--- +type: Component +title: BodyInferrer +description: Composes ControllerInspector and SchemaInspector into typed body field lists for create and update actions. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/inspectors/body_inferrer.rb +tags: [body-inference, sample-values] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: body_inferrer.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/inspectors/body_inferrer.rb +--- + +# Overview + +Only `create` and `update` get a body.[^src] Names come from +[ControllerInspector](/inspection/controller-inspector.md), types from +[SchemaInspector](/inspection/schema-inspector.md); each field is seeded with +`description: ""` and `example: SampleValue.for(type)` (see [SampleValue](/rendering/sample-value.md)). + +# Rules + +- **`required`** = column is `NOT NULL` **and** has no default. Unknown column → `string`, not required. +- Returns `nil` (not `[]`) when nothing is permitted — [Config::Builder](/config/builder.md) uses that + to omit the `body:` key entirely. +- Results are cached per controller so both actions share one parse.[^src] +- Verbose defaults are returned as **fresh hashes per call** — see + [YAML anchors pitfall](/pitfalls/yaml-anchors.md). This method is duplicated in Builder — see + [duplicated defaults](/pitfalls/duplicated-defaults.md). diff --git a/.okf/inspection/controller-inspector.md b/.okf/inspection/controller-inspector.md new file mode 100644 index 0000000..a7f1186 --- /dev/null +++ b/.okf/inspection/controller-inspector.md @@ -0,0 +1,30 @@ +--- +type: Component +title: ControllerInspector +description: Prism AST pass that extracts permitted attribute names from any permit call in a controller file. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/inspectors/controller_inspector.rb +tags: [prism, body-inference] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: controller_inspector.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/inspectors/controller_inspector.rb +--- + +# Overview + +Parses `app/controllers/_controller.rb` with Prism and collects every literal symbol/string +argument of any `permit` call, plus the top-level keys of hash arguments.[^src] Feeds +[BodyInferrer](/inspection/body-inferrer.md). Static parsing was chosen over loading the class — see +[static analysis with Prism](/decisions/static-analysis-with-prism.md). + +# Deliberately coarse + +- The permit list is **per file, not per action**: the assumption is that strong params live in one + shared `*_params` method used by both `create` and `update`.[^src] A controller with different + permits per action gets the union on both. +- Any call named `permit` counts, regardless of receiver. +- Nested and splat permits are partial/unsupported — see [known limitations](/operations/known-limitations.md). +- Missing file → `[]` (no body inferred), never an error. diff --git a/.okf/inspection/index.md b/.okf/inspection/index.md new file mode 100644 index 0000000..91fb92e --- /dev/null +++ b/.okf/inspection/index.md @@ -0,0 +1,7 @@ +# Inspection + +* [RouteInspector](route-inspector.md) - Normalizes the Rails route set into flat route hashes and applies built-in and user filters. +* [ControllerInspector](controller-inspector.md) - Prism AST pass that extracts permitted attribute names from any permit call in a controller file. +* [SchemaInspector](schema-inspector.md) - Best-effort lookup of the ActiveRecord model behind a controller. +* [BodyInferrer](body-inferrer.md) - Composes ControllerInspector and SchemaInspector into typed body fields for create and update. +* [JsonRouteDetector](json-route-detector.md) - Static Prism-based classifier that decides whether a route returns JSON (--api-only). diff --git a/.okf/inspection/json-route-detector.md b/.okf/inspection/json-route-detector.md new file mode 100644 index 0000000..bbb4ce0 --- /dev/null +++ b/.okf/inspection/json-route-detector.md @@ -0,0 +1,33 @@ +--- +type: Component +title: JsonRouteDetector +description: Static Prism-based classifier that decides whether a route returns JSON, powering --api-only. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/inspectors/json_route_detector.rb +tags: [prism, api-only, filtering] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: json_route_detector.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/inspectors/json_route_detector.rb +--- + +# Decision logic + +1. Controller's superclass chain reaches `ActionController::API` → every action is JSON. +2. Otherwise, the action's `def` body contains `render` with a `json:` key (kwarg or hash-rocket, + also inside `respond_to`) → JSON. +3. Otherwise → not JSON.[^src] + +Why strict on unknowns: see [strict --api-only](/decisions/api-only-strict.md). + +# Implementation notes + +- Each file parsed **once per detector instance**; one AST feeds `SuperclassVisitor` and `JsonActionVisitor`. +- Parent resolution: `Api::BaseController`.underscore → `app/controllers/api/base_controller.rb`, recursively. + A **placeholder cache entry is written before recursing** to break cycles.[^src] +- `SuperclassVisitor` takes the **first** class in the file. +- Parent from a gem (file absent) → `:unknown` (strict), but per-action `render json:` detection still runs. +- Gaps: helper methods, `render template:, formats: :json`, included modules — see + [known limitations](/operations/known-limitations.md). diff --git a/.okf/inspection/route-inspector.md b/.okf/inspection/route-inspector.md new file mode 100644 index 0000000..ea49cda --- /dev/null +++ b/.okf/inspection/route-inspector.md @@ -0,0 +1,33 @@ +--- +type: Component +title: RouteInspector +description: Normalizes the Rails route set into flat route hashes and applies built-in and user filters. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/inspectors/route_inspector.rb +tags: [filtering] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: route_inspector.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/inspectors/route_inspector.rb +--- + +# Overview + +First stage of the [pipeline](/overview/pipeline.md). Emits one hash per (route × verb): +`{ verb:, path:, controller:, action:, name:, path_params: }`.[^src] + +# Behaviour worth knowing + +- **Filter order:** controller blacklist → controller whitelist → action blacklist → path + internal/user prefixes. Blacklist effectively wins over whitelist because it runs first. + Matching rules live in [controller matching](/config/controller-matching.md). +- **`INTERNAL_PREFIXES` is hardcoded** (`/rails/info`, `/rails/conductor`, `/rails/mailers`, + `/rails/active_storage`, `/rails/action_mailbox`, `/action_cable`, `/assets`). New Rails-core + prefixes must be added here; user `ignored_path_prefixes` only add to it.[^src] +- Routes without `controller`/`action` defaults (e.g. engine mounts, redirects) are silently skipped — + this also keeps the gem's own [dev mount](/distribution/dev-mount.md) out of the docs. +- Paths are normalized: `(.:format)` and trailing `/` stripped; empty becomes `/`. +- Multi-verb `match via: [...]` arrives as `"GET|POST"` and is split into separate entries. +- Path params are extracted with `/:(\w+)/` — glob segments (`*path`) are not captured.[^src] diff --git a/.okf/inspection/schema-inspector.md b/.okf/inspection/schema-inspector.md new file mode 100644 index 0000000..0d38bdb --- /dev/null +++ b/.okf/inspection/schema-inspector.md @@ -0,0 +1,27 @@ +--- +type: Component +title: SchemaInspector +description: Best-effort lookup of the ActiveRecord model behind a controller to get column type, nullability and default. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/inspectors/schema_inspector.rb +tags: [body-inference] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: schema_inspector.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/inspectors/schema_inspector.rb +--- + +# Overview + +Resolves the model by taking the **last** controller segment, singularizing and camelizing it +(`api/v1/users` → `User`), then reads `columns_hash`.[^src] Feeds [BodyInferrer](/inspection/body-inferrer.md). + +# Non-obvious + +- **Namespace is discarded**: `admin/users` resolves to top-level `User`, never `Admin::User`. +- It rescues `StandardError` and returns `{}` — DB not reachable, model missing, anything. Schema + inference failing is invisible by design; fields just fall back to `string` / not required.[^src] +- The resolver is injectable (`model_resolver:`), which is how tests avoid ActiveRecord. +- Custom inflections affect resolution — see [known limitations](/operations/known-limitations.md). diff --git a/.okf/log.md b/.okf/log.md new file mode 100644 index 0000000..732c5e3 --- /dev/null +++ b/.okf/log.md @@ -0,0 +1,6 @@ +# Update Log + +## 2026-11-13 +* **Update**: CLAUDE.md now lists both copies of the duplicated defaults — [duplicated defaults](/pitfalls/duplicated-defaults.md). +* **Creation**: Initial bundle produced from the gem source (v0.1.2), README, CHANGELOG and CLAUDE.md — [pipeline](/overview/pipeline.md). +* **Creation**: Recorded two code-level findings not documented elsewhere — [duplicated defaults](/pitfalls/duplicated-defaults.md) and [scaffolded response example is always {}](/pitfalls/scaffold-response-example-empty.md). diff --git a/.okf/operations/index.md b/.okf/operations/index.md new file mode 100644 index 0000000..45fc920 --- /dev/null +++ b/.okf/operations/index.md @@ -0,0 +1,5 @@ +# Operations + +* [Testing](testing.md) - Local suite, Rails matrix, CI and smoke scripts. +* [Release checklist](release.md) - Version, changelog, packaging check, MFA push. +* [Known limitations](known-limitations.md) - Accepted gaps; do not fix without an explicit ask. diff --git a/.okf/operations/known-limitations.md b/.okf/operations/known-limitations.md new file mode 100644 index 0000000..a56028c --- /dev/null +++ b/.okf/operations/known-limitations.md @@ -0,0 +1,33 @@ +--- +type: Limitation +title: Known limitations (do not fix without an explicit ask) +description: Accepted gaps in inference, detection and YAML round-tripping that are intentional or deferred. +tags: [prism, yaml, api-only] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: claude + title: CLAUDE.md — Known limitations + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/CLAUDE.md + - id: readme + title: README — Limitations / --api-only known gaps + resource: https://github.com/jacksonpires/rails-api-docs#limitations +--- + +# List + +| Limitation | Where | +|-----------|-------| +| Nested permits → top-level keys only | [ControllerInspector](/inspection/controller-inspector.md) | +| Splat permits (`permit(*ARGS)`) not resolved | [ControllerInspector](/inspection/controller-inspector.md) | +| Inline YAML comments lost on re-run | [Config::Loader](/config/loader.md) | +| PATCH and PUT for one update → two endpoints (intentional; hide one with `show: false`) | [RouteInspector](/inspection/route-inspector.md) | +| `new`/`edit` included by default (opt out via `ignored_actions`) | [RouteInspector](/inspection/route-inspector.md) | +| Custom inflections may misname sections / miss models | [SchemaInspector](/inspection/schema-inspector.md) | +| `--api-only` misses helper-method renders, `render template:, formats: :json`, included modules | [JsonRouteDetector](/inspection/json-route-detector.md) | + +[^claude] [^readme] + +The CLAUDE.md rule: these are known and **must not be "fixed" without an explicit request**. +Root cause for most of them: [static analysis with Prism](/decisions/static-analysis-with-prism.md). diff --git a/.okf/operations/release.md b/.okf/operations/release.md new file mode 100644 index 0000000..1bd6d08 --- /dev/null +++ b/.okf/operations/release.md @@ -0,0 +1,26 @@ +--- +type: Runbook +title: Release checklist +description: Steps to cut a gem release, including the packaging check that 0.1.0 missed. +tags: [packaging] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: changelog + title: CHANGELOG.md + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/CHANGELOG.md + - id: gemspec + title: rails-api-docs.gemspec + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/rails-api-docs.gemspec +--- + +# Steps + +1. Bump `lib/rails-api-docs/version.rb`; add a dated CHANGELOG entry.[^changelog] +2. Full suite green on the matrix ([testing](/operations/testing.md)). +3. `gem build rails-api-docs.gemspec` and list the files: every `lib/rails-api-docs/*` subdirectory + (including `doc/`) must be present — see [gitignore packaging pitfall](/pitfalls/gitignore-doc-packaging.md). +4. `gem push` — the gemspec sets `rubygems_mfa_required = "true"`, so MFA is required.[^gemspec] + +Released so far: 0.1.0 (yanked), 0.1.1, 0.1.2. diff --git a/.okf/operations/testing.md b/.okf/operations/testing.md new file mode 100644 index 0000000..564d5bf --- /dev/null +++ b/.okf/operations/testing.md @@ -0,0 +1,40 @@ +--- +type: Runbook +title: Running tests and the compatibility matrix +description: How to run the minitest suite locally, per Rails version, in CI, and the end-to-end smoke scripts. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/.github/workflows/ci.yml +tags: [testing] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: ci + title: .github/workflows/ci.yml + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/.github/workflows/ci.yml + - id: claude + title: CLAUDE.md — How to run + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/CLAUDE.md +--- + +# Local + +```bash +bundle install +bundle exec rake test # ~185 runs, < 1s +BUNDLE_GEMFILE=gemfiles/rails_7.1.gemfile bundle exec rake test +``` + +Tests drive a real `ActionDispatch::Routing::RouteSet` (injected via `route_source`) — no dummy app. + +# Matrix + +CI runs Ruby 3.1–4.0 × Rails 7.1–8.1 (Ruby 3.1 excluded for Rails 8.x).[^ci] Adding a Rails minor = +new `gemfiles/rails_X.Y.gemfile` + CI matrix entry + README compatibility table. The `rails` dev dependency is in +the root `Gemfile` (not the gemspec) so per-version gemfiles can pin it without Bundler override warnings.[^claude] + +# Smoke tests + +`/tmp/rad_smoke_test.sh` (real host app, hits `/rails/api-docs`) and `/tmp/rad_smoke_build.sh` +(rake task, `OUTPUT=`, missing-config branch). They live outside the repo and may not exist on a new machine. + +Quirks: [test and Ruby 3 quirks](/pitfalls/ruby-testing-quirks.md). diff --git a/.okf/overview/glossary.md b/.okf/overview/glossary.md new file mode 100644 index 0000000..aab3e54 --- /dev/null +++ b/.okf/overview/glossary.md @@ -0,0 +1,21 @@ +--- +type: Overview +title: Glossary +description: Terms used across the gem's code and docs — section, endpoint identity, scaffold, verbose YAML, dev mount. +tags: [yaml] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +--- + +# Terms + +| Term | Meaning | +|------|---------| +| **Section** | One controller's group of endpoints in the YAML, keyed by controller path (`api/v1/users`). The key is stable; `name` is display-only. See [YAML config format](/config/yaml-format.md). | +| **Endpoint identity** | `"#{method} #{path}"` — the only thing [Config::Appender](/config/appender.md) uses to decide whether a route is new. | +| **Scaffold** | The YAML produced by the generators from code inspection ([pipeline](/overview/pipeline.md)). | +| **Pragmatic vs verbose YAML** | Default scaffold emits only commonly edited keys; `--verbose-yaml` emits every key. See [the decision](/decisions/pragmatic-default-yaml.md). | +| **Dev mount** | The engine route at `/rails/api-docs` that re-renders on every request. See [dev mount](/distribution/dev-mount.md). | +| **Internal prefixes** | Rails-core paths always hidden by [RouteInspector](/inspection/route-inspector.md); user filters stack on top. | +| **Field** | Any row rendered by `render_field`: body field, param, request/response header, response schema entry. See [Doc::Renderer](/rendering/renderer.md). | diff --git a/.okf/overview/index.md b/.okf/overview/index.md new file mode 100644 index 0000000..2696fd0 --- /dev/null +++ b/.okf/overview/index.md @@ -0,0 +1,4 @@ +# Overview + +* [Generation and rendering pipeline](pipeline.md) - How routes, controllers and AR schema become an editable YAML, and how that YAML becomes one self-contained HTML page. +* [Glossary](glossary.md) - Terms used across the gem's code and docs. diff --git a/.okf/overview/pipeline.md b/.okf/overview/pipeline.md new file mode 100644 index 0000000..db59832 --- /dev/null +++ b/.okf/overview/pipeline.md @@ -0,0 +1,48 @@ +--- +type: Overview +title: Generation and rendering pipeline +description: How routes, controllers and AR schema become an editable YAML, and how that YAML becomes one self-contained HTML page. +tags: [yaml, html, prism] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: entry + title: lib/rails-api-docs.rb (require order) + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs.rb + - id: generator + title: InitGenerator#create_or_update_config_file + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/generators/rails-api-docs/init/init_generator.rb + - id: renderer + title: Doc::Renderer + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/doc/renderer.rb +--- + +# Overview + +The gem has **two halves joined by one hand-edited file**, `config/rails-api-docs.yml`: + +1. **Scaffold (write side)** — run by the generators, at dev time only.[^generator] + [RouteInspector](/inspection/route-inspector.md) lists routes → + optional [JsonRouteDetector](/inspection/json-route-detector.md) filter (`--api-only`) → + [BodyInferrer](/inspection/body-inferrer.md) (which composes + [ControllerInspector](/inspection/controller-inspector.md) + [SchemaInspector](/inspection/schema-inspector.md)) → + [Config::Builder](/config/builder.md) assembles the hash → + either written fresh or merged by [Config::Appender](/config/appender.md). +2. **Render (read side)** — [Config::Loader](/config/loader.md) parses the YAML → + [Doc::Renderer](/rendering/renderer.md) (ERB + [CurlRenderer](/rendering/curl-renderer.md)) → one HTML string.[^renderer] + That string is served live by the [dev mount](/distribution/dev-mount.md) or written to disk by the + [build task](/distribution/build-task.md). + +The two halves never talk directly: the YAML is the contract (see [YAML config format](/config/yaml-format.md)). +That is why the render side tolerates any missing key — the user may have deleted it. + +# Load order + +Everything is required eagerly from the entry file; the Engine is only loaded when +`Rails::Engine` is defined, so the pure-Ruby pieces stay unit-testable without Rails.[^entry] + +# Working on the gem + +Before changing anything, run the suite as in [testing](/operations/testing.md); before shipping, follow the +[release checklist](/operations/release.md). Accepted gaps are in [known limitations](/operations/known-limitations.md). diff --git a/.okf/pitfalls/duplicated-defaults.md b/.okf/pitfalls/duplicated-defaults.md new file mode 100644 index 0000000..f60d79a --- /dev/null +++ b/.okf/pitfalls/duplicated-defaults.md @@ -0,0 +1,34 @@ +--- +type: Pitfall +title: Duplicated defaults that can drift +description: DEFAULT_GENERAL exists in both Builder and Renderer, and verbose_field_defaults in both Builder and BodyInferrer. +tags: [drift-risk] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T14:00:00Z +sources: + - id: builder + title: Config::Builder::DEFAULT_GENERAL / #verbose_field_defaults + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/config/builder.rb + - id: renderer + title: Doc::Renderer::DEFAULT_GENERAL + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/doc/renderer.rb + - id: bi + title: BodyInferrer#verbose_field_defaults + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/inspectors/body_inferrer.rb +--- + +# Problem + +Two identical copies each of: + +- `DEFAULT_GENERAL` — in [Config::Builder](/config/builder.md)[^builder] (what gets scaffolded) and + [Doc::Renderer](/rendering/renderer.md)[^renderer] (what fills missing keys at render time). +- `verbose_field_defaults` — in Builder (path params) and [BodyInferrer](/inspection/body-inferrer.md)[^bi] (body fields). + +Changing a default color/title or adding a verbose key in one place only will make scaffold and render +disagree. CLAUDE.md's "Where to edit what" table lists both copies. + +# Rule + +Edit both copies together (and the CSS vars in the template), or consolidate into one module. diff --git a/.okf/pitfalls/engine-class-macros.md b/.okf/pitfalls/engine-class-macros.md new file mode 100644 index 0000000..26aa8bf --- /dev/null +++ b/.okf/pitfalls/engine-class-macros.md @@ -0,0 +1,19 @@ +--- +type: Pitfall +title: Engine rake_tasks/generators must be class-body macros +description: rake_tasks and generators blocks silently do nothing if moved inside an initializer. +tags: [rails-engine] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: engine + title: engine.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/engine.rb +--- + +# Rule + +`rake_tasks do … end` and `generators do … end` are Railtie class-level hooks; they must sit directly in the +`Engine` class body, not inside `initializer "…" do`.[^engine] This broke once during a reorganization. +Only the mount lives in an initializer — see [dev mount](/distribution/dev-mount.md). diff --git a/.okf/pitfalls/gitignore-doc-packaging.md b/.okf/pitfalls/gitignore-doc-packaging.md new file mode 100644 index 0000000..959b0bc --- /dev/null +++ b/.okf/pitfalls/gitignore-doc-packaging.md @@ -0,0 +1,24 @@ +--- +type: Pitfall +title: Unanchored gitignore pattern dropped lib/.../doc from the gem +description: A "doc/" ignore pattern matched lib/rails-api-docs/doc/, so 0.1.0 shipped without its renderers and was yanked. +tags: [packaging] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: changelog + title: CHANGELOG 0.1.1 + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/CHANGELOG.md +--- + +# What happened + +The gemspec builds its file list from git, and `.gitignore` had `doc/`, which matches a `doc/` directory +at **any depth**. `lib/rails-api-docs/doc/*` (renderer, curl renderer, responder, file builder) was never +committed, 0.1.0 crashed at boot with `cannot load such file`, and was yanked.[^changelog] + +# Rule + +Anchor root-only ignores (`/doc/`). Before releasing, inspect the built gem's file list for every +`lib/` subdirectory. See [release checklist](/operations/release.md). diff --git a/.okf/pitfalls/gsub-backslash-trap.md b/.okf/pitfalls/gsub-backslash-trap.md new file mode 100644 index 0000000..edeb94d --- /dev/null +++ b/.okf/pitfalls/gsub-backslash-trap.md @@ -0,0 +1,23 @@ +--- +type: Pitfall +title: gsub replacement-string backslash trap in shell escaping +description: str.gsub("'", "'\\''") treats \' as the post-match reference; the block form must be used. +tags: [curl, testing] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: CurlRenderer#shell_escape + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/doc/curl_renderer.rb +--- + +# Problem + +In a `gsub` replacement **string**, `\'` means "post-match", so the string form duplicates content instead of +escaping quotes. + +# Rule + +Keep `str.gsub("'") { "'\\''" }` (block form).[^src] If touched, run +`test_escapes_single_quotes_in_body_for_shell` before committing. Lives in [CurlRenderer](/rendering/curl-renderer.md). diff --git a/.okf/pitfalls/index.md b/.okf/pitfalls/index.md new file mode 100644 index 0000000..3ca5546 --- /dev/null +++ b/.okf/pitfalls/index.md @@ -0,0 +1,9 @@ +# Pitfalls + +* [gsub backslash trap](gsub-backslash-trap.md) - Use the block form when shell-escaping single quotes. +* [Engine class macros](engine-class-macros.md) - rake_tasks/generators must stay in the Engine class body. +* [gitignore packaging bug](gitignore-doc-packaging.md) - Unanchored doc/ pattern dropped files from 0.1.0. +* [YAML anchors](yaml-anchors.md) - Shared default objects produce anchors in the scaffold. +* [Duplicated defaults](duplicated-defaults.md) - DEFAULT_GENERAL and verbose_field_defaults exist twice. +* [Scaffolded response example is always {}](scaffold-response-example-empty.md) - The synthesized response never runs for scaffolded endpoints. +* [Test and Ruby 3 quirks](ruby-testing-quirks.md) - render helper clash; brace string-keyed hashes. diff --git a/.okf/pitfalls/ruby-testing-quirks.md b/.okf/pitfalls/ruby-testing-quirks.md new file mode 100644 index 0000000..dab9da6 --- /dev/null +++ b/.okf/pitfalls/ruby-testing-quirks.md @@ -0,0 +1,21 @@ +--- +type: Pitfall +title: Test and Ruby 3 quirks +description: Generator TestCase clashes with a helper named render, and string-keyed hashes must be braced when passed next to kwargs. +tags: [testing] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: claude + title: CLAUDE.md — Conventions + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/CLAUDE.md +--- + +# Rules + +- In `Rails::Generators::TestCase` tests, don't define a helper called `render` — it collides. Use another name.[^claude] +- Hashes with string keys passed to a method that also takes kwargs: always wrap in explicit `{}`; Ruby 3 can + otherwise treat them as keyword arguments. + +See [testing](/operations/testing.md). diff --git a/.okf/pitfalls/scaffold-response-example-empty.md b/.okf/pitfalls/scaffold-response-example-empty.md new file mode 100644 index 0000000..94617e2 --- /dev/null +++ b/.okf/pitfalls/scaffold-response-example-empty.md @@ -0,0 +1,34 @@ +--- +type: Pitfall +title: Scaffolded endpoints always show {} as the response example +description: Because the scaffold always writes responses["200"] with example "", the renderer's synthesized response from body examples never runs for them. +tags: [sample-values, html] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: builder + title: Config::Builder#response_stub + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/config/builder.rb + - id: renderer + title: Doc::Renderer#responses_for / #default_response_example + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/doc/renderer.rb + - id: tpl + title: api_docs.html.erb response body block + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/templates/api_docs.html.erb +--- + +# Behaviour + +- [Config::Builder](/config/builder.md) emits `responses: { "200": { description: "", example: "" } }` on every endpoint.[^builder] +- [Doc::Renderer](/rendering/renderer.md)`#responses_for` honours a non-empty `responses` hash verbatim and only + synthesizes from body examples (`default_response_example`) when `responses` is absent.[^renderer] +- The template replaces a blank example with `{}`.[^tpl] + +So for a freshly scaffolded `create`, the cURL shows the inferred body but the response panel shows `{}`. +The [field-example rule](/decisions/field-example-source-of-truth.md) only reaches the response panel for +hand-written endpoints without `responses`. + +# Status + +Observed from code on 2026-11-13; not yet decided whether this is intended. Treat as a known quirk until confirmed. diff --git a/.okf/pitfalls/yaml-anchors.md b/.okf/pitfalls/yaml-anchors.md new file mode 100644 index 0000000..3e4bf85 --- /dev/null +++ b/.okf/pitfalls/yaml-anchors.md @@ -0,0 +1,19 @@ +--- +type: Pitfall +title: Shared default objects make YAML.dump emit anchors +description: Reusing the same hash/array instance across fields produces &1/*1 anchors in the scaffold; defaults must be fresh per call. +tags: [yaml] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: bi + title: BodyInferrer#verbose_field_defaults comment + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/inspectors/body_inferrer.rb +--- + +# Rule + +`YAML.dump` turns object identity into anchors (`enum: &1 []` … `enum: *1`). Verbose defaults are therefore +**methods returning new hashes**, not frozen constants.[^bi] Applies to [Config::Builder](/config/builder.md) +and [BodyInferrer](/inspection/body-inferrer.md). diff --git a/.okf/rendering/curl-renderer.md b/.okf/rendering/curl-renderer.md new file mode 100644 index 0000000..b5e619f --- /dev/null +++ b/.okf/rendering/curl-renderer.md @@ -0,0 +1,29 @@ +--- +type: Component +title: Doc::CurlRenderer +description: Builds the copy-pasteable multi-line cURL command for an endpoint, with correct shell escaping. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/doc/curl_renderer.rb +tags: [curl, sample-values] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: curl_renderer.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/doc/curl_renderer.rb +--- + +# Precedence rules + +- **Body**: `request_example` verbatim → JSON of `body` fields (each field's `example`, else + [SampleValue](/rendering/sample-value.md)) → no `--data`.[^src] +- **URL**: each `in: path` param's `:name` replaced by its `example`, else type sample. Query params are not appended. +- **Headers**: user `headers` in YAML order, then an `Authorization` placeholder derived from `auth` + (`bearer`/`basic`/custom string; `none` → nothing) **unless** the user already declared Authorization + (case-insensitive). +- `Content-Type: application/json` is added only when a body is present. + +# Shell escaping + +Single quotes become `'\''` using the **block form** of `gsub` — see +[gsub replacement-string trap](/pitfalls/gsub-backslash-trap.md).[^src] diff --git a/.okf/rendering/html-template.md b/.okf/rendering/html-template.md new file mode 100644 index 0000000..26c2594 --- /dev/null +++ b/.okf/rendering/html-template.md @@ -0,0 +1,35 @@ +--- +type: Component +title: HTML template (api_docs.html.erb) +description: The single ERB template holding layout, inlined CSS theme variables and the client-side JS (search, tag filter, tabs, copy). +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/templates/api_docs.html.erb +tags: [html] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: api_docs.html.erb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/templates/api_docs.html.erb + - id: changelog + title: CHANGELOG 0.1.2 — tag-filter pill fix + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/CHANGELOG.md +--- + +# Overview + +Three-column layout: sidebar (search + tag filter), central field tables, right column with cURL and +per-status response tabs. Colors flow from `general_configurations` into CSS custom properties.[^src] +Rendered by [Doc::Renderer](/rendering/renderer.md). + +# Conventions + +- **Trim mode `-`**: control tags end with `-%>`. New tags must follow it or the output sprouts blank lines. +- Never expand field markup inline — call `render_fields(...)`. +- `show_curl` / `show_examples` gate the right column blocks. +- Client JS: text search ANDs with a single exclusive tag filter; copy buttons use + `navigator.clipboard` with an `execCommand('copy')` fallback for non-secure contexts. +- CSS rules that set `display` on an element toggled via the `hidden` attribute need an explicit + `[hidden] { display: none }` — this was the 0.1.2 "Filtered by" pill bug.[^changelog] +- `preview/api-docs.html` is the original static mockup, **not** gem output; `preview/api-docs-rendered*.html` + are real renders kept for visual comparison. diff --git a/.okf/rendering/index.md b/.okf/rendering/index.md new file mode 100644 index 0000000..c7457bc --- /dev/null +++ b/.okf/rendering/index.md @@ -0,0 +1,6 @@ +# Rendering + +* [Doc::Renderer](renderer.md) - YAML → HTML via ERB, with render_field as the single field-markup helper. +* [HTML template](html-template.md) - Layout, inlined CSS theme variables and client-side JS. +* [Doc::CurlRenderer](curl-renderer.md) - Multi-line cURL command with correct shell escaping. +* [SampleValue](sample-value.md) - Single source of truth for type-derived placeholder values. diff --git a/.okf/rendering/renderer.md b/.okf/rendering/renderer.md new file mode 100644 index 0000000..68a6fb5 --- /dev/null +++ b/.okf/rendering/renderer.md @@ -0,0 +1,32 @@ +--- +type: Component +title: Doc::Renderer +description: Turns the parsed YAML into the self-contained HTML page via ERB, with render_field as the single field-markup helper. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/doc/renderer.rb +tags: [html] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: renderer.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/doc/renderer.rb +--- + +# Overview + +`ERB.new(template, trim_mode: "-").result(binding)` — template helpers are **public** methods so the ERB +binding reaches them.[^src] Template: [HTML template](/rendering/html-template.md). Output is a single string +with all CSS/JS inlined — see [self-contained HTML](/decisions/self-contained-html.md). + +# Rules worth keeping + +- **`render_field` is the only place field markup is built**; body, params, request headers, response headers + and response schema all go through it. Badge order is fixed: format → in → read-only → write-only → + nullable → required → min/max/default/pattern metas.[^src] Add a new per-field attribute there, never inline in ERB. +- `general` merges YAML over its own `DEFAULT_GENERAL` (a copy — see [duplicated defaults](/pitfalls/duplicated-defaults.md)). +- `visible_sections` drops `show: false` sections/endpoints and sections left empty. +- `responses_for` honours `responses:` verbatim when present; otherwise synthesizes one `200` from + `response_example` or the body sample. Because the scaffold always writes `responses`, the synthesized + path rarely runs — see [scaffolded response example is always {}](/pitfalls/scaffold-response-example-empty.md). +- `endpoint_id` (section slug + method + slugged path) is the DOM anchor; changing it breaks deep links. diff --git a/.okf/rendering/sample-value.md b/.okf/rendering/sample-value.md new file mode 100644 index 0000000..6871558 --- /dev/null +++ b/.okf/rendering/sample-value.md @@ -0,0 +1,33 @@ +--- +type: Component +title: SampleValue +description: Single source of truth for type-derived placeholder values used when a field has no example. +resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/sample_value.rb +tags: [sample-values] +generated: + by: claude-code/claude-opus-5-5 + at: 2026-11-13T12:00:00Z +sources: + - id: src + title: sample_value.rb + resource: https://github.com/jacksonpires/rails-api-docs/blob/main/lib/rails-api-docs/sample_value.rb +--- + +# Schema + +| Type | Sample | +|------|--------| +| string, text | `"example"` | +| integer, bigint | `1` | +| float, decimal | `1.0` | +| boolean | `true` | +| date | `"2026-01-01"` | +| datetime, time | `"2026-01-01T00:00:00Z"` | +| anything else | `nil` (→ JSON `null`, meaning "fill this in") | + +[^src] + +Consumers: [BodyInferrer](/inspection/body-inferrer.md), [Config::Builder](/config/builder.md), +[CurlRenderer](/rendering/curl-renderer.md), [Doc::Renderer](/rendering/renderer.md). New type mappings go here +only. The narrow mapping is intentional — guessing for niche types (json, uuid, …) would look authoritative. +Policy for when it applies: [field example is the source of truth](/decisions/field-example-source-of-truth.md). diff --git a/CLAUDE.md b/CLAUDE.md index 1847ac5..79aba2c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,10 @@ Notes for future sessions working on this gem. Does not duplicate the README — focuses on design decisions, gotchas, and how to contribute without breaking things. +## Knowledge management: OKF + +**OKF (Open Knowledge Format) is the system of record for everything about this gem.** Knowledge, design decisions, and documentation are recorded via OKF (use the `okf` skill) in the bundle at `.okf/` (start at `.okf/index.md`). When you learn something non-obvious, make a decision, or change behavior, capture or update it in the OKF bundle. Before answering "what do we know about X?" or "why was X done this way?", consult the OKF bundle first. + ## Architecture in one sentence `RouteInspector` (routes) + `ControllerInspector` (Prism AST of `params.permit`) + `SchemaInspector` (AR columns) → `Config::Builder` assembles hash → `Config::Appender` merges with existing YAML → `Doc::Renderer` (ERB + `CurlRenderer`) → self-contained HTML. @@ -60,11 +64,13 @@ Order of badges in a field-row matters for visual hierarchy — see the method b ### `field["example"]` is the single source of truth for sample values `CurlRenderer#body_json` and `Renderer#default_response_example` both prefer `field["example"]` over the type-derived `sample_value` fallback. The Builder + BodyInferrer seed `example:` for every inferred field, so by the time the renderer runs, there's almost always a real value to display. If you add a new place that needs a placeholder, follow the same precedence: user example wins; fall back to `RailsApiDocs::SampleValue.for(type)`. +**Caveat:** `Renderer#default_response_example` only runs when an endpoint has **no** `responses:` key. The scaffold always writes `responses["200"]` with `example: ""`, so a freshly scaffolded endpoint shows `{}` in the response panel; the body-example synthesis only applies to hand-written endpoints without `responses`. Whether that is intended is still open. + ### `RailsApiDocs::SampleValue` is the single source of truth for type→sample -Three consumers (BodyInferrer, Builder for path params, CurlRenderer, Renderer) all call `SampleValue.for(type)`. Adding a new type maps in one place. +Four consumers (BodyInferrer, Builder for path params, CurlRenderer, Renderer) all call `SampleValue.for(type)`; the private `sample_value` methods in `CurlRenderer` and `Renderer` only delegate to it. Adding a new type maps in one place. ### Pragmatic vs verbose YAML scaffold -Default emits the commonly-edited subset (`description`, `example` on every field; minimal `responses["200"]` stub). `--verbose-yaml` (or `RailsApiDocs.configuration.verbose_yaml = true`) emits **every** key with defaults — useful for discoverability, costly in lines per endpoint (~10× larger). The verbose defaults live in `verbose_field_defaults` / `verbose_endpoint_meta` methods (not constants — return fresh hashes per call so `YAML.dump` doesn't emit anchors). +Default emits the commonly-edited subset (`description`, `example` on every field; minimal `responses["200"]` stub). `--verbose-yaml` (or `RailsApiDocs.configuration.verbose_yaml = true`) emits **every** key with defaults — useful for discoverability, costly in lines per endpoint (~10× larger). The verbose defaults live in `verbose_field_defaults` (duplicated in `Config::Builder` and `BodyInferrer`, keep both in sync) / `Config::Builder#verbose_endpoint_meta` methods (not constants — return fresh hashes per call so `YAML.dump` doesn't emit anchors). ## Filters & extensibility @@ -87,7 +93,7 @@ User-facing filters on `Configuration`: When both filters apply, blacklist (`ignored_controllers`) wins over whitelist (`only_controllers`). -**Note:** the `ignored_controllers` string-match was changed to suffix-match in this same change (v0.1.0 was never released, so no migration impact). The previous semantics were exact-match. +**Note:** the `ignored_controllers` string-match was changed from exact-match to suffix-match before v0.1.0 shipped, so no released version ever had the old semantics (no migration impact). ### CLI parsing of `--only-controllers` (4 forms) @@ -118,14 +124,16 @@ CLI flag (`--api-only`) wins when both set; `--no-api-only` lets you override co ## Where to edit what -| To change… | File | -|------------------------------------|--------------------------------------------------------| -| visual / HTML layout | `lib/rails-api-docs/templates/api_docs.html.erb` | -| default colors | `Config::Builder::DEFAULT_GENERAL` + CSS vars in ERB | -| field type inference | `Inspectors::BodyInferrer` | -| sample value for type X | `CurlRenderer#sample_value` and `Renderer#sample_value`| -| new route filters | `Inspectors::RouteInspector` + `Configuration` | -| dev mount behavior | `Doc::Responder` (logic) + `engine.rb` (mount) | +| To change… | File | +|------------------------------------|----------------------------------------------------------------------------------------| +| visual / HTML layout | `lib/rails-api-docs/templates/api_docs.html.erb` | +| default colors / general defaults | `Config::Builder::DEFAULT_GENERAL` **and** `Doc::Renderer::DEFAULT_GENERAL` + CSS vars in ERB (keep both copies in sync) | +| field type inference | `Inspectors::BodyInferrer` | +| sample value for type X | `RailsApiDocs::SampleValue.for` (`lib/rails-api-docs/sample_value.rb`) | +| verbose field defaults | `Config::Builder#verbose_field_defaults` **and** `BodyInferrer#verbose_field_defaults` (keep in sync) | +| new route filters | `Inspectors::RouteInspector` + `Configuration` | +| dev mount behavior | `Doc::Responder` (logic) + `engine.rb` (mount) | +| project knowledge / decisions | OKF bundle in `.okf/` | ## Known limitations (do NOT "fix" without explicit ask)