rails-api-docs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac61ebf23cfaad87159b23315b863391492c5f5e54266ead2947798e4fa3d8e1
+  data.tar.gz: 042122d214d9da045aecdea97c55165d8182c5cf988601565c0d2d86c8b79128
+SHA512:
+  metadata.gz: 3ec043b12d508bcecffdd7f7122715c5988f04e60bfb2899ba5d8f825cbf88ff22d0cd1e06676d3ac2e3c40e13757970a5278fad058a5bcdad6bf89a74d8a846
+  data.tar.gz: 5bb4d2bf08b469c698886b68abfbe45f495285bf9d2fa4f278c006405d766090a6c63410e7cafa93beb01fa635d9fec6f7a8b0ab379b27764ee563d181e7a992

data/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+## [0.1.0] - Unreleased
+
+Initial release.
+
+### Inspection & inference
+
+- **`Inspectors::RouteInspector`**: walks `Rails.application.routes`,
+  normalizes paths (strips `(.:format)`), filters Rails internals
+  (`/rails/info`, `/rails/active_storage`, …), groups by controller,
+  supports multi-verb `match` and namespaced paths (`api/v1/users`).
+- **`Inspectors::ControllerInspector`** (Prism AST): extracts permitted
+  attribute names from `params.permit(:a, :b, …)` calls anywhere in the
+  controller file. Handles flat permits, hash-rocket form, and nested
+  permits (top-level keys only).
+- **`Inspectors::SchemaInspector`**: resolves controller → ActiveRecord
+  model and reads `columns_hash` for type and nullability metadata.
+  Best-effort — returns `{}` when the model can't be resolved.
+- **`Inspectors::BodyInferrer`**: composes Controller + Schema to produce
+  typed `body:` field lists for `create`/`update` actions, with sensible
+  fallbacks (`string` type, `required: false`) when inspectors come up
+  empty.
+- **`Inspectors::JsonRouteDetector`** (Prism AST): decides if an endpoint
+  is JSON-returning. Walks the controller's superclass chain looking for
+  `ActionController::API`; falls back to per-action `render json:`
+  detection inside `DefNode` bodies (kwarg and hash-rocket form, inside
+  `respond_to` blocks too). Cached per-controller.
+
+### YAML generation & merge
+
+- **`Config::Builder`**: assembles the full config — `general_configurations`
+  with Rails-themed defaults (`#CC0000` primary), `sections` grouped by
+  controller, endpoints with method/path/name/description/show, inferred
+  path params, body fields from the inferrer, and a response stub.
+- **`Config::Appender` (append-only re-runs)**: re-running
+  `rails g rails-api-docs:update` only adds new routes; existing entries —
+  including user edits to descriptions, body fields, examples, headers,
+  responses — are never modified. Endpoint identity is `"#{method} #{path}"`.
+- **`Config::Loader`**: parses existing YAML; `Loader.header` extracts
+  the leading `#`-comment block so it survives re-runs verbatim.
+- **`RailsApiDocs::SampleValue`**: single source of truth for
+  type-derived placeholder values (`integer → 1`, `string → "example"`,
+  `date → "2026-01-01"`, …). Shared between inferrer, builder, curl
+  renderer, and HTML renderer.
+
+### Generators
+
+- **Two generator commands** (one implementation): `rails-api-docs:init`
+  for the first scaffold and `rails-api-docs:update` for re-runs.
+  `UpdateGenerator < InitGenerator` aliases the namespace; same code, same
+  flags, semantically distinct invocation.
+- **`--api-only`**: filters scaffold to JSON-returning routes only,
+  via `JsonRouteDetector`. Persistent via
+  `RailsApiDocs.configuration.api_only = true`.
+- **`--only-controllers`**: whitelist controllers by name. Accepts
+  space-, comma-, or bracket-separated forms
+  (`users posts`, `users,posts`, `[users,posts]`). Bare names match
+  across namespaces (`users` matches `users` and `api/v1/users`);
+  slash-qualified names are exact. Persistent via
+  `RailsApiDocs.configuration.only_controllers = […]`.
+- **`--verbose-yaml`**: emits every possible YAML key per endpoint and
+  field with defaults (full discoverability at the cost of file size).
+  Persistent via `RailsApiDocs.configuration.verbose_yaml = true`.
+  Composes with all other flags.
+- **Other filtering knobs**: `Configuration#ignored_path_prefixes`,
+  `#ignored_controllers` (strings or regexps; same boundary-aware
+  matching as `only_controllers`), `#ignored_actions`. Blacklist wins
+  over whitelist when both apply.
+
+### YAML schema
+
+- **Pragmatic default**: every inferred body field and path param ships
+  with `description: ""` and `example: <type-sample>` — users edit
+  values without remembering key names. A minimal `responses["200"]`
+  stub is included for every endpoint.
+- **Verbose mode** additionally emits `format`, `enum`, `default`,
+  `min`/`max`, `min_length`/`max_length`, `pattern`, `read_only`,
+  `write_only`, `nullable` per field; and `deprecated`, `auth`, `tags`,
+  `headers`, `request_example`, plus a full `responses["200"]` with
+  `headers: []` and `schema: []`.
+- **Response shape**: `responses["XXX"]` accepts `description`,
+  `example` (raw string), `headers` (array of field hashes), and
+  `schema` (typed response fields rendered as field rows).
+
+### HTML renderer
+
+- **Three-column self-contained output**: sidebar, central column with
+  field tables, right column with cURL and response examples. All CSS
+  and JS inlined — no external assets, no asset pipeline.
+- **CSS variables driven by `general_configurations`**: changing
+  `primary_color` / `secondary_color` re-themes the whole page.
+- **Unified `render_field` helper**: single source of truth for field
+  rendering. Used by body, params, request headers, response headers,
+  and response schema. Renders all field-level attributes as badges,
+  metas, descriptions, and inline `Example:` lines.
+- **Endpoint-level badges**: `deprecated` (red badge + strikethrough
+  title), `auth` (dark monospace badge: "Bearer auth", "Basic auth",
+  custom), `tags` (clickable chips).
+- **`Doc::CurlRenderer`**: multi-line cURL with proper shell escaping
+  (single quotes via the `'\''` block-form `gsub`). Supports
+  `request_example` overrides, per-param `example:` substitution in the
+  URL, and auto-injects user-declared `headers:` plus an `Authorization`
+  placeholder when `auth:` is set.
+- **Multi-response support**: `responses:` keyed by status code with
+  per-status tabs in the right column (2xx green, 4xx amber, 5xx red);
+  the central column renders headers + schema per status when present.
+- **Response title + copy buttons**: every cURL block and response
+  block has a `<button>` copy icon that copies the currently-active
+  `<pre>` content (curl command or active response tab). Uses
+  `navigator.clipboard.writeText` with `document.execCommand('copy')`
+  fallback for non-secure contexts. Visual flash + checkmark on success.
+- **Tag click filtering**: clicking a tag pill filters the sidebar to
+  endpoints carrying that tag. Single-tag exclusive with toggle (same
+  tag = clear, different tag = switch). Combines with the text search
+  via AND. "Filtered by: <tag> ×" pill shown between search and section
+  list. Accessible: `<button>` elements, `aria-pressed`, `aria-live`.
+- **Field example propagation**: `field["example"]` is the single
+  source of truth for sample values — it flows into the cURL `--data`
+  body and into the default response example block, with the
+  type-derived sample as fallback.
+
+### Distribution
+
+- **Dev mount at `/rails/api-docs`**: `Rails::Engine` mounts a
+  `DocsController` in `development` that re-renders the HTML from the
+  current YAML on every request — no build step while iterating.
+  Friendly setup page when YAML doesn't exist yet.
+- **`rake rails-api-docs:build`**: reads the YAML and writes
+  `public/api-docs.html`. Supports `CONFIG=` and `OUTPUT=` env overrides.
+- **Publish-ready gemspec metadata**: `homepage_uri`, `source_code_uri`
+  (pointing at `/tree/main` so RubyGems shows both), `changelog_uri`,
+  `bug_tracker_uri`, `documentation_uri`, and
+  `rubygems_mfa_required = "true"` (enforces MFA on every `gem push`).
+
+### Tests
+
+- 185 minitest cases covering inspectors, config build/append/load,
+  renderer, curl renderer, file builder, responder, init/update
+  generators, and JSON route detector. Uses
+  `ActionDispatch::Routing::RouteSet` directly — no dummy Rails app
+  required.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jackson Pires
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.