Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions .okf/config/appender.md
Original file line number Diff line number Diff line change
@@ -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]
31 changes: 31 additions & 0 deletions .okf/config/builder.md
Original file line number Diff line number Diff line change
@@ -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).
39 changes: 39 additions & 0 deletions .okf/config/configuration.md
Original file line number Diff line number Diff line change
@@ -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).
29 changes: 29 additions & 0 deletions .okf/config/controller-matching.md
Original file line number Diff line number Diff line change
@@ -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 `/<pattern>` (`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).
8 changes: 8 additions & 0 deletions .okf/config/index.md
Original file line number Diff line number Diff line change
@@ -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.
22 changes: 22 additions & 0 deletions .okf/config/loader.md
Original file line number Diff line number Diff line change
@@ -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).
40 changes: 40 additions & 0 deletions .okf/config/yaml-format.md
Original file line number Diff line number Diff line change
@@ -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.<controller_path>` | `name`, `description`, `show`, `endpoints[]`. Key is the stable controller path. |
| `endpoints[]` | Only `method` + `path` required. Identity = `"#{method} #{path}"`. |
| field arrays | `params`, `body`, `headers`, `responses.<status>.headers`, `responses.<status>.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).
25 changes: 25 additions & 0 deletions .okf/decisions/api-only-strict.md
Original file line number Diff line number Diff line change
@@ -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).
29 changes: 29 additions & 0 deletions .okf/decisions/append-only-merge.md
Original file line number Diff line number Diff line change
@@ -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).
22 changes: 22 additions & 0 deletions .okf/decisions/field-example-source-of-truth.md
Original file line number Diff line number Diff line change
@@ -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).
10 changes: 10 additions & 0 deletions .okf/decisions/index.md
Original file line number Diff line number Diff line change
@@ -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.
22 changes: 22 additions & 0 deletions .okf/decisions/init-update-alias.md
Original file line number Diff line number Diff line change
@@ -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).
23 changes: 23 additions & 0 deletions .okf/decisions/nil-default-cli-flags.md
Original file line number Diff line number Diff line change
@@ -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).
26 changes: 26 additions & 0 deletions .okf/decisions/pragmatic-default-yaml.md
Original file line number Diff line number Diff line change
@@ -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).
Loading
Loading