docit 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb189284c9d9b8ad90f9d39fccaea0265223c3be58009b95b51b0dfbc12a3d78
-  data.tar.gz: 5bd6b3277e7686470f1c24bc2824b2cd9ec97ebc785d9e19fefe9fafe7a2be1d
+  metadata.gz: 19ca1ea84419aa3ec1c1605fec67c6355027d866de1b9e6b0d8fb27472b91602
+  data.tar.gz: a8fc557d32361a3729a9133791100bea3c7bf94e4c2f0ca55351eff4760efafe
 SHA512:
-  metadata.gz: f921f704eb18446ecc475377d7fa8f0604c34349182139fa79ac26dd76260e04028b0b4443ca300e877298c96423ac5d8cc04b5a0887c6fa379a2752de8d6c21
-  data.tar.gz: 1b6fbfc6aae77f31e74700243535e12be9c6caae790e87614903e7538e769746d774e4d31899fc3617fee01896f0f2a7e2a489fa0026d35e08cc5afd602e7c13
+  metadata.gz: 4614b2cc382920b578400ddbccb8afb0eb8a32830307e0fd75fc3a175678f218d7f658e82b61678422d520c6f6c841fa5643d36d563b6cacf0bd4233bbed655f
+  data.tar.gz: fe46a50539ba08a2783b8e1f4d95a2e313fc1a043f78dee017ad4dd47cba8166f5cb8341bf5cbf732b4e7f7a776e9966e12efcce4c1a1b3a3b2c08cf2887acf1

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-16
+
+### Added
+- Scalar API Reference as a second documentation UI alongside Swagger UI
+- New routes: `/api-docs/scalar` and `/api-docs/swagger` for direct access to each UI
+- `config.default_ui` option (`:scalar` or `:swagger`) to control which UI renders at the root `/api-docs` path
+- Navigation bar across both UIs for one-click switching between Scalar and Swagger
+- Modular renderer architecture (`Docit::UI::BaseRenderer`, `SwaggerRenderer`, `ScalarRenderer`) for easy extension
+
+### Changed
+- Default documentation UI is now Scalar (previously Swagger UI)
+- `config.description` now defaults to a welcome message instead of an empty string
+- Install generator template now documents the `default_ui` option
+- UI controller refactored from monolithic HTML generation to thin dispatcher with pluggable renderers
+
+## [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 +52,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,44 @@
 
 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
+  - [Documentation UIs](#documentation-uis)
+  - [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
 
@@ -25,13 +62,13 @@ rails generate docit:install
 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
+2. Mounts the documentation 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.
+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.
 
@@ -45,17 +82,20 @@ Docit.configure do |config|
   config.version     = "1.0.0"
   config.description = "Backend API documentation"
 
+  # 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 Swagger UI sidebar):
+  # Tag descriptions (shown in the documentation sidebar):
   config.tag "Users", description: "User account management"
   config.tag "Auth",  description: "Authentication endpoints"
 
-  # Server URLs (shown in Swagger UI server dropdown):
+  # 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"
@@ -85,7 +125,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 +454,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.
 
@@ -429,11 +471,24 @@ For each undocumented endpoint, Docit:
 
 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 built-in API client, dark mode, code samples |
+| `/api-docs/swagger` | Swagger UI | Classic OpenAPI explorer |
+| `/api-docs/spec` | Raw JSON | OpenAPI 3.0.3 spec |
+
+Both UIs include a navigation bar to switch between them. Set `config.default_ui = :swagger` to make Swagger the default at `/api-docs`.
+
 ## How it works
 
 1. `swagger_doc` 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 Swagger UI at `/api-docs`, pointing it at the generated spec
+3. The **Engine** serves the configured documentation UI at `/api-docs`, pointing it at the generated spec
 
 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`.
 

data/app/controllers/docit/ui_controller.rb

@@ -4,10 +4,16 @@ 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
+      render_ui(Docit.configuration.default_ui)
+    end
+
+    def swagger
+      render_ui(:swagger)
+    end
+
+    def scalar
+      render_ui(:scalar)
     end
 
     def spec
@@ -17,52 +23,23 @@ module Docit
 
     private
 
-    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)
+    RENDERERS = {
+      swagger: UI::SwaggerRenderer,
+      scalar: UI::ScalarRenderer
+    }.freeze
+
+    def render_ui(ui_name)
+      renderer = RENDERERS.fetch(ui_name).new(spec_url: spec_url, nav_paths: nav_paths)
+      render html: renderer.render.html_safe, layout: false
+    end
+
+    def spec_url
+      "#{request.base_url}#{Docit::Engine.routes.url_helpers.spec_path}"
+    end
 
-      <<~HTML
-        <!DOCTYPE html>
-        <html lang="en">
-        <head>
-          <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@#{SWAGGER_UI_VERSION}/swagger-ui.css" />
-          <style>
-            html { box-sizing: border-box; overflow-y: scroll; }
-            *, *:before, *:after { box-sizing: inherit; }
-            body { margin: 0; background: #fafafa; }
-          </style>
-        </head>
-        <body>
-          <div id="swagger-ui"></div>
-          <script src="https://unpkg.com/swagger-ui-dist@#{SWAGGER_UI_VERSION}/swagger-ui-bundle.js"></script>
-          <script>
-            SwaggerUIBundle({
-              url: #{spec_url_json},
-              dom_id: '#swagger-ui',
-              presets: [
-                SwaggerUIBundle.presets.apis,
-                SwaggerUIBundle.SwaggerUIStandalonePreset
-              ],
-              layout: "BaseLayout",
-              deepLinking: true,
-              showExtensions: 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>
-        </html>
-      HTML
+    def nav_paths
+      helpers = Docit::Engine.routes.url_helpers
+      { swagger: helpers.swagger_path, scalar: helpers.scalar_path }
     end
   end
 end

data/config/routes.rb

@@ -2,5 +2,7 @@
 
 Docit::Engine.routes.draw do
   root to: "ui#index"
+  get "swagger", to: "ui#swagger"
+  get "scalar", to: "ui#scalar"
   get "spec", to: "ui#spec", defaults: { format: :json }
 end

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

@@ -3,6 +3,8 @@
 module Docit
   module Ai
     class AutodocRunner
+      MAX_INVALID_OUTPUT_RETRIES = 2
+
       attr_reader :results
 
       def initialize(controller_filter: nil, dry_run: false, input: $stdin, output: $stdout)
@@ -50,7 +52,7 @@ module Docit
       end
 
       def check_base_setup!
-        if !(defined?(Rails) && Rails.respond_to?(:root) && Rails.root)
+        if defined?(Rails) == false || Rails.respond_to?(:root) == false || Rails.root.nil?
           raise Docit::Error, "Docit requires a Rails application. Run this command from your app root."
         end
 
@@ -82,20 +84,20 @@ module Docit
         @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."
+        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
       end
@@ -103,6 +105,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............."
 
@@ -114,16 +117,45 @@ module Docit
             @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})"
+          retries = 0
+          invalid_output_retries = 0
+          validation_error = nil
+
+          begin
+            prompt = builder.build(validation_error: validation_error)
+            doc_block = client.generate(prompt).strip
+            doc_block = strip_markdown_fences(doc_block)
+            DocBlockValidator.new(
+              controller: gap[:controller],
+              action: gap[:action],
+              doc_block: doc_block
+            ).validate!
+
+            generated[gap[:controller]] << doc_block
+            @results[:generated] += 1
+            @output.puts " done"
+          rescue Docit::Ai::InvalidDocBlockError => e
+            invalid_output_retries += 1
+            if invalid_output_retries <= MAX_INVALID_OUTPUT_RETRIES
+              validation_error = e.message
+              retry
+            end
+
+            @output.puts " failed (invalid doc DSL: #{e.message})"
+          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
@@ -152,11 +184,11 @@ module Docit
 
       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
+        if 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
       end
 
       def strip_markdown_fences(text)

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/configuration.rb

@@ -6,6 +6,11 @@ module Docit
   module Ai
     class Configuration
       CONFIG_FILE = ".docit_ai.yml"
+      GENERATED_FILE_COMMENT = <<~TEXT
+        # If you want to change the model and start Docit setup again,
+        # rerun: rails generate docit:install
+
+      TEXT
 
       PROVIDERS = %w[openai anthropic groq].freeze
 
@@ -51,11 +56,13 @@ module Docit
           config = new(provider: provider, model: model, api_key: api_key)
           raise Error, "Invalid configuration" if config.valid? == false
 
-          File.write(config_path, {
+          yaml = {
             "provider" => config.provider,
             "model" => config.model,
             "api_key" => config.api_key
-          }.to_yaml)
+          }.to_yaml
+
+          File.write(config_path, GENERATED_FILE_COMMENT + yaml)
           File.chmod(0o600, config_path)
 
           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/ai/prompt_builder.rb

@@ -66,7 +66,7 @@ module Docit
         @gap = gap
       end
 
-      def build
+      def build(validation_error: nil)
         <<~PROMPT
           You are generating Docit DSL documentation for a Ruby on Rails API endpoint.
 
@@ -89,12 +89,18 @@ module Docit
           Rules:
           - Output ONLY the `doc :#{@gap[:action]} do ... end` block
           - No module wrapper, no explanation, no markdown fences
+          - Use exactly `doc :#{@gap[:action]} do ... end` for the requested action
+          - Use ONLY the DSL methods listed above
           - Infer parameters from the path (e.g., {id} → path parameter)
           - Infer request body from params usage in the controller
           - Infer response structure from render calls
+          - Inside `request_body` and `response` blocks, define nested data only with `property ..., type: :object` or `property ..., type: :array`
+          - Never call standalone helpers such as `object`, `array`, `string`, `integer`, `number`, or `boolean`
+          - Return valid Ruby that can be `instance_eval`'d as-is
           - Use realistic examples
           - Include appropriate error responses
           - Use the controller name to determine appropriate tags
+          #{validation_feedback(validation_error)}
         PROMPT
       end
 
@@ -114,10 +120,22 @@ module Docit
       end
 
       def controller_file_path
-        return nil if defined?(Rails) == false || Rails.respond_to?(:root) == false || Rails.root.nil?
+        return nil unless defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
 
         relative = @gap[:controller].underscore
-        Rails.root.join("app", "controllers", "#{relative}.rb").to_s
+        ::Rails.root.join("app", "controllers", "#{relative}.rb").to_s
+      end
+
+      def validation_feedback(validation_error)
+        return "" if validation_error.nil? || validation_error.empty?
+
+        <<~FEEDBACK
+
+          Previous attempt failed Docit validation:
+          - #{validation_error}
+
+          Regenerate the block and fix that error.
+        FEEDBACK
       end
     end
   end

data/lib/docit/ai.rb

@@ -6,6 +6,7 @@ require_relative "ai/openai_client"
 require_relative "ai/anthropic_client"
 require_relative "ai/groq_client"
 require_relative "ai/gap_detector"
+require_relative "ai/doc_block_validator"
 require_relative "ai/prompt_builder"
 require_relative "ai/doc_writer"
 require_relative "ai/tag_injector"

data/lib/docit/configuration.rb

@@ -3,18 +3,31 @@
 module Docit
   # Holds global API documentation settings: metadata, authentication, tags, and servers.
   class Configuration
+    SUPPORTED_UIS = %i[scalar swagger].freeze
+
     attr_accessor :title, :version, :description, :base_url
+    attr_reader :default_ui
 
     def initialize
       @title = "API Documentation"
       @version = "1.0.0"
-      @description = ""
+      @description = "Welcome to the API documentation. Browse the endpoints below to get started."
       @base_url = "/"
+      @default_ui = :scalar
       @security_schemes = {}
       @tags = []
       @servers = []
     end
 
+    def default_ui=(value)
+      ui = value.to_sym
+      unless SUPPORTED_UIS.include?(ui)
+        raise ArgumentError, "Unsupported UI: #{value}. Must be one of: #{SUPPORTED_UIS.join(", ")}"
+      end
+
+      @default_ui = ui
+    end
+
     def auth(type, **options)
       case type.to_s.downcase
       when "basic"

data/lib/docit/ui/base_renderer.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Docit
+  module UI
+    class BaseRenderer
+      attr_reader :spec_url, :title, :nav_paths
+
+      def initialize(spec_url:, nav_paths: {})
+        @spec_url = spec_url
+        @nav_paths = nav_paths
+        @title = ERB::Util.html_escape(Docit.configuration.title)
+      end
+
+      def render
+        raise NotImplementedError, "#{self.class}#render must be implemented"
+      end
+
+      private
+
+      def nav_bar(active:)
+        swagger_active = active == :swagger
+        scalar_active = active == :scalar
+
+        <<~HTML
+          <nav style="
+            display: flex; align-items: center; gap: 8px;
+            padding: 6px 16px;
+            background: #1a1a2e; color: #fff;
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            font-size: 13px; position: sticky; top: 0; z-index: 9999;
+          ">
+            <span style="font-weight: 600; margin-right: auto;">#{title}</span>
+            #{nav_link("Swagger", nav_paths[:swagger], active: swagger_active)}
+            #{nav_link("Scalar", nav_paths[:scalar], active: scalar_active)}
+          </nav>
+        HTML
+      end
+
+      def nav_link(label, path, active:)
+        escaped_path = ERB::Util.html_escape(path)
+        style = if active
+                  "color: #fff; text-decoration: none; padding: 4px 12px; border-radius: 4px; background: rgba(255,255,255,0.15); font-weight: 500;"
+                else
+                  "color: rgba(255,255,255,0.7); text-decoration: none; padding: 4px 12px; border-radius: 4px;"
+                end
+
+        %(<a href="#{escaped_path}" style="#{style}">#{label}</a>)
+      end
+
+      def spec_url_json
+        JSON.generate(spec_url)
+      end
+    end
+  end
+end

data/lib/docit/ui/scalar_renderer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Docit
+  module UI
+    class ScalarRenderer < BaseRenderer
+      def render
+        <<~HTML
+          <!DOCTYPE html>
+          <html lang="en">
+          <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            <title>#{title}</title>
+            <style>
+              body { margin: 0; }
+            </style>
+          </head>
+          <body>
+            #{nav_bar(active: :scalar)}
+            <script id="api-reference"></script>
+            <script>
+              document.getElementById('api-reference').dataset.configuration = JSON.stringify({
+                spec: { url: #{spec_url_json} },
+                theme: "elysiajs",
+                showSidebar: true,
+                hideDownloadButton: false,
+                hideModels: false,
+                searchHotKey: "k"
+              })
+            </script>
+            <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+          </body>
+          </html>
+        HTML
+      end
+    end
+  end
+end

data/lib/docit/ui/swagger_renderer.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Docit
+  module UI
+    class SwaggerRenderer < BaseRenderer
+      VERSION = "5.32.2"
+
+      def render
+        <<~HTML
+          <!DOCTYPE html>
+          <html lang="en">
+          <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            <title>#{title}</title>
+            <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@#{VERSION}/swagger-ui.css" />
+            <style>
+              html { box-sizing: border-box; overflow-y: scroll; }
+              *, *:before, *:after { box-sizing: inherit; }
+              body { margin: 0; background: #fafafa; }
+            </style>
+          </head>
+          <body>
+            #{nav_bar(active: :swagger)}
+            <div id="swagger-ui"></div>
+            <script src="https://unpkg.com/swagger-ui-dist@#{VERSION}/swagger-ui-bundle.js"></script>
+            <script>
+              SwaggerUIBundle({
+                url: #{spec_url_json},
+                dom_id: '#swagger-ui',
+                presets: [
+                  SwaggerUIBundle.presets.apis,
+                  SwaggerUIBundle.SwaggerUIStandalonePreset
+                ],
+                layout: "BaseLayout",
+                deepLinking: true,
+                showExtensions: 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>
+          </html>
+        HTML
+      end
+    end
+  end
+end

data/lib/docit/version.rb

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

data/lib/docit.rb

@@ -12,6 +12,9 @@ require_relative "docit/doc_file"
 require_relative "docit/route_inspector"
 require_relative "docit/schema_generator"
 require_relative "docit/dsl"
+require_relative "docit/ui/base_renderer"
+require_relative "docit/ui/swagger_renderer"
+require_relative "docit/ui/scalar_renderer"
 
 # Docit is a decorator-style API documentation gem for Ruby on Rails.
 # It generates OpenAPI 3.0.3 specs from clean DSL macros on your controllers.
@@ -47,4 +50,5 @@ module Docit
   end
 end
 
+require_relative "docit/engine" if defined?(Rails::Engine)
 require_relative "docit/ai"

data/lib/generators/docit/install/templates/initializer.rb

@@ -1,15 +1,18 @@
 # frozen_string_literal: true
 
 Docit.configure do |config|
-  # The title shown in Swagger UI
+  # The title shown in the API documentation UI
   config.title = "<%= Rails.application.class.module_parent_name rescue 'My API' %>"
 
   # API version
   config.version = "1.0.0"
 
-  # Description shown in Swagger UI
+  # Description shown on the introduction page
   config.description = "API documentation powered by Docit"
 
+  # Documentation UI: :scalar (default) or :swagger
+  # config.default_ui = :scalar
+
   # Authentication scheme (options: :bearer, :basic, :api_key)
   # config.auth :bearer
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - S13G
@@ -68,6 +68,9 @@ files:
 - lib/docit/route_inspector.rb
 - lib/docit/schema_definition.rb
 - lib/docit/schema_generator.rb
+- lib/docit/ui/base_renderer.rb
+- lib/docit/ui/scalar_renderer.rb
+- lib/docit/ui/swagger_renderer.rb
 - lib/docit/version.rb
 - lib/generators/docit/ai_setup/ai_setup_generator.rb
 - lib/generators/docit/install/install_generator.rb