docit 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e48afeb14f8b73781bf089a31b30616c00d4aa053f079668fbecbc7215ea13e2
-  data.tar.gz: dd1ea68be0fb59dd014af55bb457fe110e2da2227fe56a0216d75c5051046215
+  metadata.gz: cb189284c9d9b8ad90f9d39fccaea0265223c3be58009b95b51b0dfbc12a3d78
+  data.tar.gz: 5bd6b3277e7686470f1c24bc2824b2cd9ec97ebc785d9e19fefe9fafe7a2be1d
 SHA512:
-  metadata.gz: ba5dadbd366f719b4420c515ad252380e4e5fd66137bb183e6b8d109426b0cf828eed12918658ea3a9af6e55d73f2c8e806e7a92c9d600d3a58e1fb643319576
-  data.tar.gz: 17690c65bec465a9b3479d80375a558a72bec94fd5677f8389e028d07d7b915e146bfa16b380ba0fb89aef33b848980033bcd38eb51ba04c6ef899c1c7c6663f
+  metadata.gz: f921f704eb18446ecc475377d7fa8f0604c34349182139fa79ac26dd76260e04028b0b4443ca300e877298c96423ac5d8cc04b5a0887c6fa379a2752de8d6c21
+  data.tar.gz: 1b6fbfc6aae77f31e74700243535e12be9c6caae790e87614903e7538e769746d774e4d31899fc3617fee01896f0f2a7e2a489fa0026d35e08cc5afd602e7c13

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [Unreleased]
 
+## [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

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,11 +1,9 @@
 # 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.
+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.
 
 Inspired by [drf-spectacular](https://github.com/tfranzel/drf-spectacular) for Django REST Framework.
 
@@ -24,13 +22,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`:
@@ -374,6 +378,57 @@ 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 |
+
+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 +456,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 +464,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,57 @@
+# 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"
+          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,168 @@
+# 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] = [] }
+
+        @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
+          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::Error => e
+          @output.puts " failed (#{e.message})"
+        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,23 @@
+# frozen_string_literal: true
+
+module Docit
+  module Ai
+    class Error < Docit::Error; 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

data/lib/docit/ai/doc_writer.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "active_support/core_ext/string/inflections"
+
+module Docit
+  module Ai
+    class DocWriter
+      def initialize(controller_name:)
+        @controller_name = controller_name
+        @module_parts = build_module_parts
+      end
+
+      def doc_file_path
+        parts = @controller_name.underscore.delete_suffix("_controller").split("/")
+        filename = "#{parts.last}_docs.rb"
+        dir_parts = parts[0..-2]
+
+        File.join(Rails.root, "app", "docs", *dir_parts, filename)
+      end
+
+      def doc_module_name
+        @controller_name.delete_suffix("Controller").gsub("::", "::") + "Docs"
+      end
+
+      def file_exists?
+        File.exist?(doc_file_path)
+      end
+
+      def controller_has_use_docs?
+        path = controller_file_path
+        return false if path && File.exist?(path) == false
+
+        File.read(path).include?("use_docs")
+      end
+
+      def inject_use_docs
+        path = controller_file_path
+        return false if path && File.exist?(path) == false
+        return false if controller_has_use_docs?
+
+        content = File.read(path)
+        class_pattern = /^(\s*class\s+\S+.*$)/
+        match = content.match(class_pattern)
+        return false if match.nil?
+
+        indent = match[1][/^\s*/] + "  "
+        use_docs_line = "#{indent}use_docs #{doc_module_name}\n"
+        content = content.sub(class_pattern, "\\1\n#{use_docs_line}")
+
+        File.write(path, content)
+        true
+      end
+
+      def write(doc_blocks)
+        if file_exists?
+          append_to_existing(doc_blocks)
+        else
+          create_new_file(doc_blocks)
+        end
+      end
+
+      private
+
+      def create_new_file(doc_blocks)
+        FileUtils.mkdir_p(File.dirname(doc_file_path))
+
+        content = build_new_file_content(doc_blocks)
+        File.write(doc_file_path, content)
+      end
+
+      def append_to_existing(doc_blocks)
+        content = File.read(doc_file_path)
+        insertion = doc_blocks.map { |block| indent_block(block, @module_parts.length + 1) }.join("\n\n")
+        closing_ends = "end\n" * @module_parts.length
+
+        content = content.rstrip
+        content = content.delete_suffix(closing_ends.rstrip)
+        content = "#{content.rstrip}\n\n#{insertion}\n#{closing_ends}"
+
+        File.write(doc_file_path, content)
+      end
+
+      def build_new_file_content(doc_blocks)
+        lines = ["# frozen_string_literal: true", ""]
+
+        @module_parts.each_with_index do |part, i|
+          lines << "#{"  " * i}module #{part}"
+        end
+
+        depth = @module_parts.length
+        lines << "#{"  " * depth}extend Docit::DocFile"
+
+        doc_blocks.each do |block|
+          lines << ""
+          lines << indent_block(block, depth)
+        end
+
+        @module_parts.length.times do |i|
+          lines << "#{"  " * (@module_parts.length - 1 - i)}end"
+        end
+
+        lines.join("\n") + "\n"
+      end
+
+      def indent_block(block, depth)
+        prefix = "  " * depth
+        block.strip.lines.map { |line| line.rstrip.empty? ? "" : "#{prefix}#{line.rstrip}" }.join("\n")
+      end
+
+      def build_module_parts
+        doc_module_name.split("::")
+      end
+
+      def controller_file_path
+        Rails.root.join("app", "controllers", "#{@controller_name.underscore}.rb").to_s
+      end
+    end
+  end
+end