docit 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39589c6800b65d7a0ad55701378b345f18277735df3511cce965bc889035e74f
-  data.tar.gz: 91c392bded5bbd0897222859feab4d68e8c0d3064d4054e6b75509a325ced2d0
+  metadata.gz: 85a7407aab5a5fea2aa0c679d469360f124884ebeac2e4479265cbcdd818210d
+  data.tar.gz: c946eea9c5a664931630b00726f33b8e5bb296c1493e799c67cd905f330cba1d
 SHA512:
-  metadata.gz: 1ea253c903e6a90eb3754ed9f4a586adcc7339c831d9623401cc4bb53256359c81e069bba4067a12379da350fbf354b50bfd14420ae0aa75c3841c74942ae5f2
-  data.tar.gz: 8441b41ae22a25f1bd29514fbdcb425b4bbd56b591da6904df0c9ad070a7ac830b1eb9338783a8c751d8f648db4826d69b7755a0f42cd320baaf8e3ebeb7c628
+  metadata.gz: 3dd0a62c6d0f138916839a7bcc445f98921abaf9e0ef477473e4dddba67f2033fd29ffb51a4803597d98f0807ee24c53d6b5a90a8d144d87c54669ee51155fef
+  data.tar.gz: d953ceef06cd91034fa79503a07da386dcefc7cdddabcb3567d1638d6546a2c484bdebd82f263d732a94b89447a9e9f6b659d7008c322d2e238e002aca286a1b

data/CHANGELOG.md

@@ -1,4 +1,13 @@
-## [Unreleased]
+## [0.5.0] - 2026-05-31
+
+### Added
+- **System Map**: a local, deterministic architecture graph at `/api-docs/system` (JSON at `/api-docs/system.json`), built from Rails routes, controllers, actions, Docit docs coverage, schemas, models, and source-derived service/job/mailer nodes — no external service required
+- System Map navigation alongside the Scalar and Swagger UIs
+- Light and dark themes for the System Map (light by default), with a toolbar toggle persisted across visits
+- **Diagram view**: interactive architecture graph with drag-to-arrange, scroll-to-zoom, pan, fit-to-screen, and PNG export; click a node to inspect its connections, with neighbouring nodes highlighted; `/` focuses node search
+- Endpoints-section filter for the diagram (Users, Orders, …) that narrows the graph to one resource and everything it touches
+- **Docs view**: a request/response reference grouped by resource, with human-readable endpoint titles derived from doc summaries (falling back to REST conventions), a documentation-coverage indicator per section, and a detail panel showing parameters, request body, and responses
+- AI section explanations in the Docs view: "Explain section" summarises how a resource's endpoints work together, gated by a coverage warning so undocumented sections don't silently spend tokens
 
 ## [0.4.0] - 2026-04-18
 

data/README.md

@@ -11,7 +11,47 @@ Decorator-style API documentation for Ruby on Rails. Write OpenAPI 3.0.3 docs wi
 ### Swagger
 ![Swagger UI](docs/images/swagger_image.png)
 
-> **Full documentation:** [docitruby.dev/docs](https://docitruby.dev/docs)
+> **Full documentation:** [doc-it.dev/docs](https://doc-it.dev/docs)
+
+## Table Of Contents
+
+- Getting started
+  - [Installation](#installation)
+  - [Configuration](#configuration)
+  - [Usage](#usage)
+- Documentation styles
+  - [Style 1: Inline (simple APIs)](#style-1-inline-simple-apis)
+  - [Style 2: Separate doc files (recommended for larger APIs)](#style-2-separate-doc-files-recommended-for-larger-apis)
+- Endpoint DSL reference
+  - [Endpoint documentation DSL](#endpoint-documentation-dsl)
+  - [Request bodies](#request-bodies)
+  - [Path parameters](#path-parameters)
+  - [Enums](#enums)
+  - [Security](#security)
+  - [Deprecated endpoints](#deprecated-endpoints)
+  - [Nested objects and arrays](#nested-objects-and-arrays)
+  - [Response examples](#response-examples)
+  - [Shared schemas (`$ref`)](#shared-schemas-ref)
+  - [File uploads](#file-uploads)
+- AI documentation
+  - [AI Automatic Documentation](#ai-automatic-documentation)
+  - [Quick start (included in install)](#quick-start-included-in-install)
+  - [Standalone commands](#standalone-commands)
+  - [Supported providers](#supported-providers)
+  - [What the AI generates](#what-the-ai-generates)
+- Runtime and development
+  - [Documentation UIs](#documentation-uis)
+  - [System Map](#system-map)
+  - [How it works](#how-it-works)
+  - [Mounting at a different path](#mounting-at-a-different-path)
+  - [JSON spec only](#json-spec-only)
+  - [Development](#development)
+  - [Contributing](#contributing)
+  - [License](#license)
+- Project docs
+  - [CHANGELOG](CHANGELOG.md)
+  - [CONTRIBUTING](CONTRIBUTING.md)
+  - [CODE OF CONDUCT](CODE_OF_CONDUCT.md)
 
 ## Installation
 
@@ -39,6 +79,8 @@ The install generator does everything in one step:
 
 Visit `/api-docs` to see your interactive API documentation (Scalar by default, Swagger UI also available at `/api-docs/swagger`).
 
+If you choose AI setup, Docit stores your provider config in `.docit_ai.yml` with restricted file permissions and adds that file to `.gitignore` when possible.
+
 ## Configuration
 
 Edit `config/initializers/docit.rb`:
@@ -48,19 +90,39 @@ Docit.configure do |config|
   config.title       = "My API"
   config.version     = "1.0.0"
   config.description = "Backend API documentation"
-  config.default_ui  = :scalar    # :scalar (default) or :swagger
 
-  config.auth :bearer              # Bearer token (JWT)
+  # Documentation UI: :scalar (default) or :swagger
+  config.default_ui  = :scalar
+
+  # Authentication: pick one (or multiple):
+  config.auth :bearer                              # Bearer token (JWT by default)
+  config.auth :basic                               # HTTP Basic
+  config.auth :api_key, name: "X-API-Key",         # API key in header
+                         location: "header"
+
+  # Tag descriptions (shown in the documentation sidebar):
   config.tag "Users", description: "User account management"
+  config.tag "Auth",  description: "Authentication endpoints"
+
+  # Server URLs (shown in the server dropdown):
   config.server "https://api.example.com", description: "Production"
+  config.server "https://staging.example.com", description: "Staging"
+  config.server "http://localhost:3000", description: "Development"
+
+  # License information:
+  config.license name: "MIT", url: "https://opensource.org/licenses/MIT"
+
+  # Contact information:
+  config.contact name: "API Team", email: "api@example.com", url: "https://example.com/support"
+
+  # Terms of service:
+  config.terms_of_service "https://example.com/tos"
 end
 ```
 
-See the [full configuration reference](https://docitruby.dev/docs/configuration) for all options including `license`, `contact`, `terms_of_service`, multiple auth schemes, and server URLs.
-
-## Quick Start
+## Usage
 
-Docit supports two styles. Choose whichever fits your project or mix both.
+Docit supports two styles for documenting endpoints. Choose whichever fits your project or mix both.
 
 ### Style 1: Inline (simple APIs)
 
@@ -73,7 +135,6 @@ class Api::V1::UsersController < ApplicationController
     tags "Users"
     response 200, "Users retrieved"
   end
-
   def index
     # your code
   end
@@ -93,62 +154,392 @@ module Api::V1::UsersDocs
 
   doc :index do
     summary "List all users"
+    description "Returns a paginated list of users"
     tags "Users"
 
+    parameter :page, location: :query, type: :integer, description: "Page number"
+
     response 200, "Users retrieved" do
       property :users, type: :array, items: :object do
         property :id, type: :integer, example: 1
         property :email, type: :string, example: "user@example.com"
       end
+      property :total, type: :integer, example: 42
+    end
+  end
+
+  doc :create do
+    summary "Create a user"
+    tags "Users"
+
+    request_body required: true do
+      property :email, type: :string, required: true
+      property :password, type: :string, required: true, format: :password
+    end
+
+    response 201, "User created" do
+      property :id, type: :integer
+    end
+
+    response 422, "Validation failed" do
+      property :errors, type: :object do
+        property :email, type: :array, items: :string
+      end
     end
   end
 end
-```
 
-```ruby
-# app/controllers/api/v1/users_controller.rb
+# app/controllers/api/v1/users_controller.rb — stays clean!
 class Api::V1::UsersController < ApplicationController
   use_docs Api::V1::UsersDocs
 
   def index
     # pure business logic
   end
+
+  def create
+    # pure business logic
+  end
+end
+```
+
+You can also mix both styles — use `use_docs` for most actions and add inline `doc_for` for one-offs:
+
+```ruby
+class Api::V1::UsersController < ApplicationController
+  use_docs Api::V1::UsersDocs        # loads :index and :create from doc file
+
+  doc_for :destroy do             # inline doc for this one action
+    summary "Delete user"
+    tags "Users"
+    response 204, "Deleted"
+  end
+
+  def index; end
+  def create; end
+  def destroy; end
 end
 ```
 
-See the [full DSL reference](https://docitruby.dev/docs/dsl-reference) for request bodies, path parameters, enums, security, nested objects, file uploads, shared schemas, and more.
+### Endpoint documentation DSL
+
+The following examples work in both `doc_for` blocks and `doc` blocks.
 
-## AI Documentation
+### Request bodies
 
-Docit can generate complete API documentation using AI. Works with OpenAI, Anthropic, or Groq (free tier available).
+```ruby
+doc_for :create do
+  summary "Create a user"
+  tags "Users"
+
+  request_body required: true do
+    property :email, type: :string, required: true, example: "user@example.com"
+    property :password, type: :string, required: true, format: :password
+    property :name, type: :string, example: "Jane Doe"
+    property :profile, type: :object do
+      property :bio, type: :string
+      property :avatar_url, type: :string, format: :uri
+    end
+  end
 
-When you run `rails generate docit:install` and choose AI automatic docs, everything is set up automatically — provider configuration, doc generation, controller wiring, and tag injection.
+  response 201, "User created" do
+    property :id, type: :integer, example: 1
+    property :email, type: :string, example: "user@example.com"
+  end
+
+  response 422, "Validation failed" do
+    property :errors, type: :object do
+      property :email, type: :array, items: :string
+    end
+  end
+end
+def create
+  # your code
+end
+```
+
+### Path parameters
+
+```ruby
+doc_for :show do
+  summary "Get a user"
+  tags "Users"
+
+  parameter :id, location: :path, type: :integer, required: true, description: "User ID"
+
+  response 200, "User found" do
+    property :id, type: :integer, example: 1
+    property :email, type: :string
+    property :name, type: :string
+  end
+
+  response 404, "User not found" do
+    property :error, type: :string, example: "Not found"
+  end
+end
+def show
+  # your code
+end
+```
+
+### Enums
+
+```ruby
+doc_for :index do
+  summary "List orders"
+  tags "Orders"
+
+  parameter :status, location: :query, type: :string,
+            enum: %w[pending shipped delivered],
+            description: "Filter by status"
+
+  response 200, "Orders list" do
+    property :orders, type: :array do
+      property :id, type: :integer
+      property :status, type: :string, enum: %w[pending shipped delivered]
+    end
+  end
+end
+```
+
+### Security
+
+Mark endpoints as requiring authentication:
+
+```ruby
+doc_for :destroy do
+  summary "Delete a user"
+  tags "Users"
+  security :bearer_auth      # references the scheme from your config
+
+  response 204, "User deleted"
+  response 401, "Unauthorized"
+end
+```
+
+### Deprecated endpoints
+
+```ruby
+doc_for :legacy_search do
+  summary "Search (legacy)"
+  tags "Search"
+  deprecated
+
+  response 200, "Results"
+end
+```
+
+### Nested objects and arrays
+
+```ruby
+response 200, "Success" do
+  property :user, type: :object do
+    property :id, type: :integer
+    property :name, type: :string
+    property :addresses, type: :array do
+      property :street, type: :string
+      property :city, type: :string
+      property :zip, type: :string
+    end
+  end
+end
+```
+
+### Response examples
+
+```ruby
+response 200, "User found" do
+  property :id, type: :integer
+  property :email, type: :string
+
+  example "admin_user",
+          { id: 1, email: "admin@example.com" },
+          description: "An admin user"
+
+  example "regular_user",
+          { id: 2, email: "user@example.com" },
+          description: "A regular user"
+end
+```
+
+### Shared schemas (`$ref`)
+
+Define reusable schemas once and reference them across multiple endpoints:
+
+```ruby
+# In config/initializers/docit.rb or a dedicated file:
+Docit.define_schema :User do
+  property :id,    type: :integer, example: 1
+  property :email, type: :string,  example: "user@example.com"
+  property :name,  type: :string,  example: "Jane Doe"
+  property :address, type: :object do
+    property :street, type: :string
+    property :city,   type: :string
+  end
+end
+
+Docit.define_schema :Error do
+  property :error,   type: :string, example: "Not found"
+  property :details, type: :array, items: :string
+end
+```
+
+Reference them in any endpoint with `schema ref:`:
+
+```ruby
+doc_for :show do
+  summary "Get user"
+  tags "Users"
+
+  response 200, "User found" do
+    schema ref: :User
+  end
+
+  response 404, "Not found" do
+    schema ref: :Error
+  end
+end
+
+doc_for :create do
+  summary "Create user"
+  tags "Users"
+
+  request_body required: true do
+    schema ref: :User
+  end
+
+  response 201, "Created" do
+    schema ref: :User
+  end
+end
+```
+
+This outputs `$ref: '#/components/schemas/User'` in the spec — Swagger UI resolves it automatically.
+
+### File uploads
+
+Use `type: :file` with `content_type: "multipart/form-data"` for file upload endpoints:
+
+```ruby
+doc_for :upload_avatar do
+  summary "Upload avatar"
+  tags "Users"
+
+  request_body required: true, content_type: "multipart/form-data" do
+    property :avatar, type: :file, required: true, description: "Avatar image"
+    property :caption, type: :string
+  end
+
+  response 201, "Avatar uploaded" do
+    property :url, type: :string, format: :uri
+  end
+end
+```
+
+`type: :file` maps to `{ type: "string", format: "binary" }` in the OpenAPI spec.
+
+## AI Automatic Documentation
+
+Docit can generate complete API documentation using AI. This works with OpenAI, Anthropic, or Groq (free tier available).
+
+### Quick start (included in install)
+
+When you run `rails generate docit:install` and choose option 1 (AI automatic docs), everything is set up automatically — provider configuration, doc generation, controller wiring, and tag injection.
+
+Before the first AI request, Docit warns that your controller source code will be sent to the selected provider and asks for confirmation in interactive terminals.
+
+### Standalone commands
+
+You can also set up AI docs separately:
 
 ```bash
-# Or set up AI docs separately:
+# Configure your AI provider (one-time setup)
 rails generate docit:ai_setup
+
+# Generate docs for all undocumented endpoints
 rails docit:autodoc
 
-# Preview without writing files:
+# Generate docs for a specific controller
+rails docit:autodoc[Api::V1::UsersController]
+
+# Preview what would be generated without writing files
 DRY_RUN=1 rails docit:autodoc
 ```
 
-See the [full AI documentation guide](https://docitruby.dev/docs/ai-documentation) for provider details, safety considerations, and standalone commands.
+### Supported providers
+
+| Provider   | Notes |
+|------------|-------|
+| OpenAI     | Requires API key from platform.openai.com |
+| Anthropic  | Requires API key from console.anthropic.com |
+| Groq       | Free tier at console.groq.com |
+
+All providers automatically retry on rate-limit (429) errors with exponential backoff, so free-tier usage works out of the box.
+
+AI configuration is stored in `.docit_ai.yml`.
+If your app does not have a `.gitignore`, add `.docit_ai.yml` manually.
+
+### What the AI generates
+
+For each undocumented endpoint, Docit:
+
+1. Reads the controller source code
+2. Inspects the route (HTTP method, path, parameters)
+3. Writes the generated doc block to `app/docs/`
+4. Injects `use_docs` into the controller
+5. Adds tag descriptions to the initializer
+
+Do not use AI autodoc on controllers that contain secrets, proprietary business rules, or internal comments you do not want sent to an external provider.
 
 ## Documentation UIs
 
+Docit ships with two documentation UIs, both reading from the same OpenAPI spec:
+
 | Path | UI | Notes |
 |------|------|-------|
 | `/api-docs` | Default (Scalar) | Configurable via `config.default_ui` |
-| `/api-docs/scalar` | Scalar API Reference | Modern UI with API client, dark mode |
+| `/api-docs/scalar` | Scalar API Reference | Modern UI with built-in API client, dark mode, code samples |
 | `/api-docs/swagger` | Swagger UI | Classic OpenAPI explorer |
+| `/api-docs/system` | System Map | Local architecture graph for routes, controllers, docs coverage, and app structure |
 | `/api-docs/spec` | Raw JSON | OpenAPI 3.0.3 spec |
 
-## How It Works
+Both UIs include a navigation bar to switch between them. Set `config.default_ui = :swagger` to make Swagger the default at `/api-docs`.
+
+## System Map
+
+Docit includes a local system map for understanding how your Rails API fits together. It builds a **deterministic** graph from Rails routes, controller actions, Docit docs, schemas, models, and source references — no external service is required to view it.
+
+Visit `/api-docs/system` to open it. It has two views, a light/dark theme toggle, and PNG export:
+
+- **Diagram** — an interactive architecture graph. Drag nodes to rearrange, scroll to zoom, and click a node to inspect its connections (its neighbours highlight while the rest fade back). Filter to a single resource with the section dropdown, or press `/` to search nodes.
+- **Docs** — a request/response reference grouped by resource. Each endpoint shows a human-readable title, its method and path, parameters, request body, and responses, drawn from your Docit docs. A coverage indicator shows how many endpoints in each section are documented.
+
+If you have an AI provider configured, the Docs view's **Explain section** button summarises how a resource's endpoints work together. It warns before running on sections with undocumented endpoints, so documenting first gives a better result.
+
+## How it works
 
 1. `doc_for` registers an **Operation** for each controller action in a global **Registry**
 2. When someone visits `/api-docs/spec`, Docit's **SchemaGenerator** combines all registered operations with your Rails routes (via **RouteInspector**) to produce an OpenAPI 3.0.3 JSON document
 3. The **Engine** serves the configured documentation UI at `/api-docs`, pointing it at the generated spec
+4. The **SystemGraph** builds a local architecture graph for `/api-docs/system`
+
+The DSL is included in all controllers automatically via a Rails Engine initializer — no manual `include` needed if you're using `ActionController::API` or `ActionController::Base`.
+
+## Mounting at a different path
+
+In `config/routes.rb`:
+
+```ruby
+mount Docit::Engine => "/docs"        # now at /docs instead of /api-docs
+```
+
+## JSON spec only
+
+If you just want the raw OpenAPI JSON (e.g., for code generation):
+
+```
+GET /api-docs/spec
+```
 
 ## Development
 
@@ -156,7 +547,7 @@ See the [full AI documentation guide](https://docitruby.dev/docs/ai-documentatio
 git clone https://github.com/S13G/docit.git
 cd docit
 bundle install
-bundle exec rspec
+bundle exec rspec        # run all tests
 ```
 
 ## Contributing

data/app/controllers/docit/ui_controller.rb

@@ -16,6 +16,31 @@ module Docit
       render_ui(:scalar)
     end
 
+    def system
+      render_ui(:system)
+    end
+
+    def system_spec
+      unless Docit.configuration.system_graph_enabled
+        return render(json: { error: "System graph disabled" }, status: :not_found)
+      end
+
+      RouteInspector.eager_load_controllers!
+      render json: SystemGraph::Generator.generate
+    end
+
+    def system_insights
+      graph = system_graph
+      insight = Ai::SystemInsightGenerator.new(
+        graph: graph,
+        selected_node_ids: selected_node_ids,
+        mode: insight_mode
+      ).generate
+      render json: { insight: insight }
+    rescue Docit::Error => e
+      render json: { error: e.message }, status: :unprocessable_entity
+    end
+
     def spec
       RouteInspector.eager_load_controllers!
       render json: SchemaGenerator.generate
@@ -25,21 +50,50 @@ module Docit
 
     RENDERERS = {
       swagger: UI::SwaggerRenderer,
-      scalar: UI::ScalarRenderer
+      scalar: UI::ScalarRenderer,
+      system: UI::SystemRenderer
     }.freeze
 
     def render_ui(ui_name)
-      renderer = RENDERERS.fetch(ui_name).new(spec_url: spec_url, nav_paths: nav_paths)
+      renderer = RENDERERS.fetch(ui_name).new(
+        spec_url: spec_url,
+        system_url: system_url,
+        system_insights_url: system_insights_url,
+        nav_paths: nav_paths
+      )
       render html: renderer.render.html_safe, layout: false
     end
 
+    def system_graph
+      RouteInspector.eager_load_controllers!
+      SystemGraph::Generator.generate
+    end
+
+    def selected_node_ids
+      params.fetch(:node_ids, "").to_s.split(",").reject(&:empty?)
+    end
+
+    # Validate at the boundary: only the known modes are honored, anything
+    # else falls back to the safe per-node default.
+    def insight_mode
+      params[:mode].to_s == "section" ? :section : :nodes
+    end
+
     def spec_url
       "#{request.base_url}#{Docit::Engine.routes.url_helpers.spec_path}"
     end
 
+    def system_url
+      "#{request.base_url}#{Docit::Engine.routes.url_helpers.system_spec_path}"
+    end
+
+    def system_insights_url
+      "#{request.base_url}#{Docit::Engine.routes.url_helpers.system_insights_path}"
+    end
+
     def nav_paths
       helpers = Docit::Engine.routes.url_helpers
-      { swagger: helpers.swagger_path, scalar: helpers.scalar_path }
+      { swagger: helpers.swagger_path, scalar: helpers.scalar_path, system: helpers.system_path }
     end
   end
 end

data/config/routes.rb

@@ -4,5 +4,8 @@ Docit::Engine.routes.draw do
   root to: "ui#index"
   get "swagger", to: "ui#swagger"
   get "scalar", to: "ui#scalar"
+  get "system.json", to: "ui#system_spec", defaults: { format: :json }, as: :system_spec
+  get "system/insights", to: "ui#system_insights", defaults: { format: :json }, as: :system_insights
+  get "system", to: "ui#system", as: :system
   get "spec", to: "ui#spec", defaults: { format: :json }
 end