docit 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e48afeb14f8b73781bf089a31b30616c00d4aa053f079668fbecbc7215ea13e2
-  data.tar.gz: dd1ea68be0fb59dd014af55bb457fe110e2da2227fe56a0216d75c5051046215
+  metadata.gz: 3fe9c345834352ce5e4219a291760ced965cdbad10084c28cbc2aabc2823a5b5
+  data.tar.gz: 86aa4599733b72c52fe66335c4581e4f69b408af1bbb00c0c2d5f42b1b7a51fe
 SHA512:
-  metadata.gz: ba5dadbd366f719b4420c515ad252380e4e5fd66137bb183e6b8d109426b0cf828eed12918658ea3a9af6e55d73f2c8e806e7a92c9d600d3a58e1fb643319576
-  data.tar.gz: 17690c65bec465a9b3479d80375a558a72bec94fd5677f8389e028d07d7b915e146bfa16b380ba0fb89aef33b848980033bcd38eb51ba04c6ef899c1c7c6663f
+  metadata.gz: 9ad86a75a50a1a1177cf7cbde2bf49f12eb7cc36e1df9fd268ff2b6519c7b01efffc680aab2484a83f3dbdfb410740633a7cabbf8072d873403deafc6c14ccd3
+  data.tar.gz: 2fbf560890376ef66614e12f961496b77ab5bfb2e994ffaeb006cc2a5ddd9ef82128115cf7d1fba39a89a889b0aec8342d487525eedad276a9b8244a6ee574d3

data/CHANGELOG.md

@@ -1,10 +1,43 @@
 ## [Unreleased]
 
+## [0.2.1] - 2026-04-11
+
+### Fixed
+- Engine autoloading: `Docit::Engine` is now properly required when Rails is present, fixing `uninitialized constant Docit::Engine` and `Could not find generator 'docit:install'` in consuming apps
+- AI provider clients (OpenAI, Anthropic, Groq) now raise `Docit::Ai::RateLimitError` on 429 responses with parsed retry-after timing
+- `AutodocRunner` now retries rate-limited requests up to 3 times with exponential backoff (capped at 5 minutes) instead of failing immediately
+
+## [0.2.0] - 2026-04-11
+
+### Added
+- Unified install generator: `rails g docit:install` now offers AI auto-docs, manual scaffolding, or skip
+- Manual scaffold mode: creates doc file placeholders with TODO markers, injects `use_docs` into controllers
+- `AutodocRunner` class: reusable orchestrator for AI doc generation (used by both install generator and rake task)
+- `ScaffoldGenerator` class: creates placeholder doc files for manual documentation
+- Groq provider support (free tier) alongside OpenAI and Anthropic
+- AI configuration generator: `rails g docit:ai_setup`
+- Tasks: `rails docit:autodoc` with preview support via `DRY_RUN=1`
+- Auto-injection of `use_docs` into controllers after doc generation
+- Auto-injection of `config.tag` entries into initializer
+
+### Changed
+- AI setup flows now retry invalid menu input instead of exiting immediately
+- AI setup flows now hide API key input in interactive terminals
+- `rails docit:autodoc` now supports `DRY_RUN=1` for preview mode
+- AI autodoc now warns before sending controller source to external providers
+- Swagger UI assets are pinned to a specific `swagger-ui-dist` version
+
+### Fixed
+- `.docit_ai.yml` is now written with restricted file permissions
+- AI provider clients now return a clean Docit error when an upstream service responds with invalid JSON
+- Swagger UI now escapes the generated spec URL before embedding it in JavaScript
+- Manual scaffolds now use `200` for `PUT` and `PATCH` responses by default
+
 ## [0.1.0] - 2026-04-08
 
 - Initial release
 - DSL: `swagger_doc` macro for inline controller documentation
-- DSL: `use_docs` + `Docit::DocFile` for separate doc files (drf-spectacular style)
+- DSL: `use_docs` + `Docit::DocFile` for separate doc files
 - Builders: request body, response, and parameter builders with nested object/array support
 - Schema `$ref` components via `Docit.define_schema`
 - File upload support (`type: :file` → `string/binary`)

data/CONTRIBUTING.md

@@ -33,7 +33,7 @@ Docit aims for high test coverage and an extensive test suite. Tests enable us t
 
 ```bash
 # Fork the repo on GitHub, then:
-git clone https://github.com/YOURGITHUBNAME/docit.git
+git clone https://github.com/S13G/docit.git
 cd docit
 
 # Install dependencies

data/README.md

@@ -1,13 +1,47 @@
 # Docit
 
-[![Gem Version](https://badge.fury.io/rb/docit.svg)](https://rubygems.org/gems/docit)
-[![CI](https://github.com/S13G/docket/actions/workflows/ci.yml/badge.svg)](https://github.com/S13G/docket/actions/workflows/ci.yml)
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-red.svg)](https://www.ruby-lang.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Decorator-style API documentation for Ruby on Rails. Write OpenAPI 3.0 docs as clean DSL macros directly on your controller actions: no separate doc files, no RSpec integration required. Just annotate and go.
-
-Inspired by [drf-spectacular](https://github.com/tfranzel/drf-spectacular) for Django REST Framework.
+Decorator-style API documentation for Ruby on Rails. Write OpenAPI 3.0.3 docs with clean controller DSL macros, separate doc modules, or AI-assisted scaffolding for undocumented endpoints.
+
+## 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
+  - [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
 
@@ -24,13 +58,19 @@ bundle install
 rails generate docit:install
 ```
 
-The generator does two things:
+The install generator does everything in one step:
 
 1. Creates `config/initializers/docit.rb` with default settings
 2. Mounts the Swagger UI engine at `/api-docs` in your routes
+3. Asks how you'd like to set up your docs:
+   - **AI automatic docs** — configure an AI provider, then Docit scans your routes and generates complete documentation for every endpoint
+   - **Manual docs** — Docit scans your routes and creates scaffolded doc files with TODO placeholders, injects `use_docs` into controllers, and lets you fill in the details
+   - **Skip** — just install the base config and set up docs later
 
 Visit `/api-docs` to see your interactive API documentation.
 
+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`:
@@ -81,7 +121,7 @@ end
 
 ### Style 2: Separate doc files (recommended for larger APIs)
 
-Keep controllers clean by defining docs in dedicated files, just like drf-spectacular:
+Keep controllers clean by defining docs in dedicated files:
 
 ```ruby
 # app/docs/api/v1/users_docs.rb
@@ -374,6 +414,59 @@ 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
+# Configure your AI provider (one-time setup)
+rails generate docit:ai_setup
+
+# Generate docs for all undocumented endpoints
+rails docit:autodoc
+
+# 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
+```
+
+### 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.
+
 ## How it works
 
 1. `swagger_doc` registers an **Operation** for each controller action in a global **Registry**
@@ -401,7 +494,7 @@ GET /api-docs/spec
 ## Development
 
 ```bash
-git clone https://github.com/S13G/docket.git
+git clone https://github.com/S13G/docit.git
 cd docit
 bundle install
 bundle exec rspec        # run all tests
@@ -409,7 +502,7 @@ bundle exec rspec        # run all tests
 
 ## Contributing
 
-Bug reports and pull requests are welcome on [GitHub](https://github.com/S13G/docket).
+Bug reports and pull requests are welcome on [GitHub](https://github.com/S13G/docit).
 
 ## License
 

data/app/controllers/docit/ui_controller.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Docit
   class UiController < ActionController::Base
+    SWAGGER_UI_VERSION = "5.32.2"
+
     def index
       render html: swagger_ui_html.html_safe, layout: false
     end
@@ -15,6 +19,7 @@ module Docit
 
     def swagger_ui_html
       spec_url = "#{request.base_url}#{Docit::Engine.routes.url_helpers.spec_path}"
+      spec_url_json = JSON.generate(spec_url)
       escaped_title = ERB::Util.html_escape(Docit.configuration.title)
 
       <<~HTML
@@ -24,7 +29,7 @@ module Docit
           <meta charset="UTF-8">
           <meta name="viewport" content="width=device-width, initial-scale=1.0">
           <title>#{escaped_title}</title>
-          <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
+          <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@#{SWAGGER_UI_VERSION}/swagger-ui.css" />
           <style>
             html { box-sizing: border-box; overflow-y: scroll; }
             *, *:before, *:after { box-sizing: inherit; }
@@ -33,10 +38,10 @@ module Docit
         </head>
         <body>
           <div id="swagger-ui"></div>
-          <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+          <script src="https://unpkg.com/swagger-ui-dist@#{SWAGGER_UI_VERSION}/swagger-ui-bundle.js"></script>
           <script>
             SwaggerUIBundle({
-              url: "#{spec_url}",
+              url: #{spec_url_json},
               dom_id: '#swagger-ui',
               presets: [
                 SwaggerUIBundle.presets.apis,
@@ -45,7 +50,14 @@ module Docit
               layout: "BaseLayout",
               deepLinking: true,
               showExtensions: true,
-              showCommonExtensions: true
+              showCommonExtensions: true,
+              requestInterceptor: function(req) {
+                var url = new URL(req.url);
+                url.protocol = window.location.protocol;
+                url.host = window.location.host;
+                req.url = url.toString();
+                return req;
+              }
             })
           </script>
         </body>

data/lib/docit/ai/anthropic_client.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Docit
+  module Ai
+    class AnthropicClient
+      API_URL = "https://api.anthropic.com/v1/messages"
+      API_VERSION = "2023-06-01"
+
+      def initialize(api_key:, model:)
+        @api_key = api_key
+        @model = model
+      end
+
+      def generate(prompt)
+        uri = URI(API_URL)
+        request = Net::HTTP::Post.new(uri)
+        request["x-api-key"] = @api_key
+        request["anthropic-version"] = API_VERSION
+        request["Content-Type"] = "application/json"
+        request.body = {
+          model: @model,
+          max_tokens: 4096,
+          messages: [{ role: "user", content: prompt }]
+        }.to_json
+
+        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: 15, read_timeout: 60) do |http|
+          http.request(request)
+        end
+
+        handle_response(response)
+      end
+
+      private
+
+      def handle_response(response)
+        body = parse_json(response, "Anthropic")
+
+        if response.is_a?(Net::HTTPSuccess) == false
+          message = body.dig("error", "message") || "Unknown API error"
+
+          if response.code == "429"
+            retry_after = response["Retry-After"]&.to_f
+            raise RateLimitError.new("Anthropic rate limit exceeded", retry_after: retry_after)
+          end
+
+          raise Error, "Anthropic API error (#{response.code}): #{message}"
+        end
+
+        body.dig("content", 0, "text") || raise(Error, "Empty response from Anthropic")
+      end
+
+      def parse_json(response, provider_name)
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise Error, "#{provider_name} returned invalid JSON (HTTP #{response.code})"
+      end
+    end
+  end
+end

data/lib/docit/ai/autodoc_runner.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Docit
+  module Ai
+    class AutodocRunner
+      attr_reader :results
+
+      def initialize(controller_filter: nil, dry_run: false, input: $stdin, output: $stdout)
+        @controller_filter = controller_filter
+        @dry_run = dry_run
+        @input = input
+        @output = output
+        @results = { gaps: [], generated: 0, files: [], tags: [] }
+      end
+
+      def run
+        check_base_setup!
+        config = load_config
+        @output.puts "Using #{config.provider}"
+        @output.puts ""
+
+        gaps = detect_gaps
+        @results[:gaps] = gaps
+
+        if gaps.empty?
+          @output.puts "All endpoints are documented!"
+          return @results
+        end
+
+        print_gaps(gaps)
+
+        if @dry_run
+          @output.puts "[dry-run] No files written."
+          return @results
+        end
+
+        confirm_source_upload!(config)
+        generated = generate_docs(gaps, config)
+        write_docs(generated)
+        inject_tags(generated)
+
+        @output.puts "Review generated files and edit as needed."
+        @results
+      end
+
+      private
+
+      def load_config
+        Docit::Ai::Configuration.load
+      end
+
+      def check_base_setup!
+        if !(defined?(Rails) && Rails.respond_to?(:root) && Rails.root)
+          raise Docit::Error, "Docit requires a Rails application. Run this command from your app root."
+        end
+
+        initializer = Rails.root.join("config", "initializers", "docit.rb")
+        if File.exist?(initializer) == false
+          raise Docit::Error, "Docit is not installed. Run: rails generate docit:install"
+        end
+
+        routes_file = Rails.root.join("config", "routes.rb")
+        if File.exist?(routes_file) && !File.read(routes_file).include?("Docit::Engine")
+          @output.puts "Warning: Docit engine is not mounted in config/routes.rb"
+          @output.puts "  Run: rails generate docit:install (or add: mount Docit::Engine => \"/api-docs\")"
+          @output.puts ""
+        end
+      end
+
+      def detect_gaps
+        detector = GapDetector.new(controller_filter: @controller_filter)
+        detector.detect
+      end
+
+      def print_gaps(gaps)
+        @output.puts "Found #{gaps.length} undocumented endpoint#{"s" if gaps.length > 1}:"
+        gaps.each { |g| @output.puts "  #{g[:method].upcase} #{g[:path]} (#{g[:controller]}##{g[:action]})" }
+        @output.puts ""
+      end
+
+      def confirm_source_upload!(config)
+        @output.puts "Docit will send controller source code to #{config.provider.capitalize} to generate documentation."
+        @output.puts "Review the endpoints first if they contain secrets or proprietary logic."
+
+        return if !(@input.respond_to?(:tty?) && @input.tty?)
+
+        loop do
+          @output.print "Continue? (y/n): "
+          choice = @input.gets.to_s.strip.downcase
+
+          case choice
+          when "y", "yes"
+            @output.puts ""
+            return
+          when "n", "no"
+            raise Docit::Error, "Autodoc cancelled."
+          else
+            @output.puts "Please enter y or n."
+          end
+        end
+      end
+
+      def generate_docs(gaps, config)
+        client = Client.for(config)
+        generated = Hash.new { |h, k| h[k] = [] }
+        max_retries = 3
+
+        @output.puts "Generating documentation............."
+
+        gaps.each_with_index do |gap, index|
+          @output.print "[#{index + 1}/#{gaps.length}] Generating #{gap[:controller]}##{gap[:action]}..."
+
+          builder = PromptBuilder.new(gap: gap)
+          if builder.source_available? == false
+            @output.puts " skipped (controller source file not found)"
+            next
+          end
+
+          prompt = builder.build
+          retries = 0
+
+          begin
+            doc_block = client.generate(prompt).strip
+            doc_block = strip_markdown_fences(doc_block)
+
+            generated[gap[:controller]] << doc_block
+            @results[:generated] += 1
+            @output.puts " done"
+          rescue Docit::Ai::RateLimitError => e
+            retries += 1
+            if retries <= max_retries
+              wait = e.retry_after || (2**retries * 10)
+              wait = [wait, 300].min # cap at 5 minutes
+              @output.puts " rate limited, waiting #{wait.round}s (attempt #{retries}/#{max_retries})..."
+              sleep(wait)
+              retry
+            else
+              @output.puts " failed (rate limit exceeded after #{max_retries} retries)"
+            end
+          rescue Docit::Ai::Error => e
+            @output.puts " failed (#{e.message})"
+          end
+        end
+
+        generated
+      end
+
+      def write_docs(generated)
+        generated.each do |controller, blocks|
+          next if blocks.empty?
+
+          writer = DocWriter.new(controller_name: controller)
+          writer.write(blocks)
+          @results[:files] << writer.doc_file_path
+
+          relative = writer.doc_file_path.sub("#{Rails.root}/", "")
+          @output.puts "  Wrote: #{relative}"
+
+          if writer.inject_use_docs
+            controller_relative = File.join("app", "controllers", "#{controller.underscore}.rb")
+            @output.puts "  Added use_docs to #{controller_relative}"
+          end
+        end
+
+        @output.puts ""
+        @output.puts "Generated docs for #{@results[:generated]} endpoint#{"s" if @results[:generated] > 1} in #{@results[:files].length} file#{"s" if @results[:files].length > 1}."
+      end
+
+      def inject_tags(generated)
+        all_tags = generated.values.flatten.join("\n").scan(/tags\s+["']([^"']+)["']/).flatten
+        return unless all_tags.any?
+
+        injected = TagInjector.new(tags: all_tags).inject
+        injected.each { |tag| @output.puts "  Added tag \"#{tag}\" to config/initializers/docit.rb" }
+        @results[:tags] = injected
+      end
+
+      def strip_markdown_fences(text)
+        text = text.sub(/\A```\w*\n/, "")
+        text.sub(/\n```\z/, "")
+      end
+    end
+  end
+end

data/lib/docit/ai/client.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Docit
+  module Ai
+    class Error < Docit::Error; end
+
+    class RateLimitError < Error
+      attr_reader :retry_after
+
+      def initialize(message, retry_after: nil)
+        @retry_after = retry_after
+        super(message)
+      end
+    end
+
+    # Factory for AI provider clients.
+    module Client
+      def self.for(config)
+        case config.provider
+        when "openai"
+          OpenaiClient.new(api_key: config.api_key, model: config.model)
+        when "anthropic"
+          AnthropicClient.new(api_key: config.api_key, model: config.model)
+        when "groq"
+          GroqClient.new(api_key: config.api_key, model: config.model)
+        else
+          raise Error, "Unsupported provider: #{config.provider}"
+        end
+      end
+    end
+  end
+end

data/lib/docit/ai/configuration.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Docit
+  module Ai
+    class Configuration
+      CONFIG_FILE = ".docit_ai.yml"
+
+      PROVIDERS = %w[openai anthropic groq].freeze
+
+      DEFAULT_MODELS = {
+        "openai" => "gpt-4o-mini",
+        "anthropic" => "claude-haiku-4-5-20251001",
+        "groq" => "llama-3.3-70b-versatile"
+      }.freeze
+
+      attr_reader :provider, :model, :api_key
+
+      def initialize(provider:, model:, api_key:)
+        @provider = provider.to_s
+        @model = model.to_s
+        @api_key = api_key.to_s
+      end
+
+      def valid?
+        PROVIDERS.include?(provider) && !model.empty? && !api_key.empty?
+      end
+
+      class << self
+        def config_path
+          Rails.root.join(CONFIG_FILE)
+        end
+
+        def configured?
+          File.exist?(config_path)
+        end
+
+        def load
+          raise Error, "AI not configured. Run: rails generate docit:ai_setup" if configured? == false
+
+          data = YAML.safe_load_file(config_path, permitted_classes: [Symbol])
+          new(
+            provider: data["provider"],
+            model: data["model"],
+            api_key: data["api_key"]
+          )
+        end
+
+        def save(provider:, model:, api_key:)
+          config = new(provider: provider, model: model, api_key: api_key)
+          raise Error, "Invalid configuration" if config.valid? == false
+
+          File.write(config_path, {
+            "provider" => config.provider,
+            "model" => config.model,
+            "api_key" => config.api_key
+          }.to_yaml)
+          File.chmod(0o600, config_path)
+
+          config
+        end
+      end
+    end
+  end
+end