docit 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb189284c9d9b8ad90f9d39fccaea0265223c3be58009b95b51b0dfbc12a3d78
-  data.tar.gz: 5bd6b3277e7686470f1c24bc2824b2cd9ec97ebc785d9e19fefe9fafe7a2be1d
+  metadata.gz: 3fe9c345834352ce5e4219a291760ced965cdbad10084c28cbc2aabc2823a5b5
+  data.tar.gz: 86aa4599733b72c52fe66335c4581e4f69b408af1bbb00c0c2d5f42b1b7a51fe
 SHA512:
-  metadata.gz: f921f704eb18446ecc475377d7fa8f0604c34349182139fa79ac26dd76260e04028b0b4443ca300e877298c96423ac5d8cc04b5a0887c6fa379a2752de8d6c21
-  data.tar.gz: 1b6fbfc6aae77f31e74700243535e12be9c6caae790e87614903e7538e769746d774e4d31899fc3617fee01896f0f2a7e2a489fa0026d35e08cc5afd602e7c13
+  metadata.gz: 9ad86a75a50a1a1177cf7cbde2bf49f12eb7cc36e1df9fd268ff2b6519c7b01efffc680aab2484a83f3dbdfb410740633a7cabbf8072d873403deafc6c14ccd3
+  data.tar.gz: 2fbf560890376ef66614e12f961496b77ab5bfb2e994ffaeb006cc2a5ddd9ef82128115cf7d1fba39a89a889b0aec8342d487525eedad276a9b8244a6ee574d3

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [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
@@ -30,7 +37,7 @@
 
 - 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/README.md

@@ -5,7 +5,43 @@
 
 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.
+## 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
 
@@ -85,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
@@ -414,6 +450,8 @@ DRY_RUN=1 rails docit:autodoc
 | 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.
 

data/lib/docit/ai/anthropic_client.rb

@@ -41,6 +41,12 @@ module Docit
 
         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
 

data/lib/docit/ai/autodoc_runner.rb

@@ -103,6 +103,7 @@ module Docit
       def generate_docs(gaps, config)
         client = Client.for(config)
         generated = Hash.new { |h, k| h[k] = [] }
+        max_retries = 3
 
         @output.puts "Generating documentation............."
 
@@ -116,14 +117,29 @@ module Docit
           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})"
+          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

data/lib/docit/ai/client.rb

@@ -4,6 +4,15 @@ 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)

data/lib/docit/ai/groq_client.rb

@@ -39,6 +39,12 @@ module Docit
 
         if response.is_a?(Net::HTTPSuccess) == false
           message = body.dig("error", "message") || "Unknown API error"
+
+          if response.code == "429"
+            retry_after = parse_retry_after(response, message)
+            raise RateLimitError.new("Groq rate limit exceeded", retry_after: retry_after)
+          end
+
           raise Error, "Groq API error (#{response.code}): #{message}"
         end
 
@@ -50,6 +56,24 @@ module Docit
       rescue JSON::ParserError
         raise Error, "#{provider_name} returned invalid JSON (HTTP #{response.code})"
       end
+
+      def parse_retry_after(response, message)
+        # Check Retry-After header first (seconds)
+        if (header = response["Retry-After"])
+          return header.to_f if header.to_f > 0
+        end
+
+        # Parse "try again in XmY.Zs" from error message
+        if message =~ /(\d+)m([\d.]+)s/
+          return (Regexp.last_match(1).to_i * 60) + Regexp.last_match(2).to_f
+        end
+
+        if message =~ /([\d.]+)s/
+          return Regexp.last_match(1).to_f
+        end
+
+        nil
+      end
     end
   end
 end

data/lib/docit/ai/openai_client.rb

@@ -39,6 +39,12 @@ module Docit
 
         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("OpenAI rate limit exceeded", retry_after: retry_after)
+          end
+
           raise Error, "OpenAI API error (#{response.code}): #{message}"
         end
 

data/lib/docit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docit
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/docit.rb

@@ -47,4 +47,5 @@ module Docit
   end
 end
 
+require_relative "docit/engine" if defined?(Rails::Engine)
 require_relative "docit/ai"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - S13G