prauga-flexdoc 0.4.1 → 0.4.2

data/lib/prauga/flexdoc/config.rb

@@ -2,6 +2,28 @@
 
 module Prauga
   module FlexDoc
+    # FlexDoc renderer configuration.
+    #
+    # @!attribute [r] path
+    #   Normalized docs mount path.
+    # @!attribute [r] spec_url
+    #   OpenAPI document URL resolved by the browser bootstrap page.
+    # @!attribute [r] title
+    #   Page and renderer title.
+    # @!attribute [r] theme
+    #   Renderer theme preset: `system`, `light`, or `dark`.
+    # @!attribute [r] try_it_enabled
+    #   Whether the Try It client is enabled.
+    # @!attribute [r] expand
+    #   Optional expansion preset or section list.
+    # @!attribute [r] try_it_default_server
+    #   Optional default server URL for Try It requests.
+    # @!attribute [r] try_it_credentials
+    #   Optional fetch credentials mode: `omit`, `same-origin`, or `include`.
+    # @!attribute [r] try_it_api_client_persistence_key
+    #   Optional persistence key, or `false` to disable.
+    # @!attribute [r] try_it_host_execution
+    #   Emits host-execution protocol metadata; execution is not implemented by this adapter.
     Config = Data.define(
       :path,
       :spec_url,
@@ -14,6 +36,18 @@ module Prauga
       :try_it_api_client_persistence_key,
       :try_it_host_execution
     ) do
+      # Create a validated configuration.
+      #
+      # @param path [String] docs mount path
+      # @param spec_url [String] OpenAPI document URL
+      # @param title [String] page and renderer title
+      # @param theme [String] renderer theme preset
+      # @param try_it_enabled [Boolean] whether Try It is enabled
+      # @param expand [String, Array<String>, nil] optional expansion preset or section list
+      # @param try_it_default_server [String, nil] optional default server URL for Try It
+      # @param try_it_credentials [String, nil] optional fetch credentials mode
+      # @param try_it_api_client_persistence_key [String, false, nil] optional persistence key
+      # @param try_it_host_execution [Boolean] emit host-execution protocol metadata; execution is not implemented by this adapter
       def initialize(
         path: "/docs",
         spec_url: "/openapi.json",

data/lib/prauga/flexdoc/host.rb

@@ -6,11 +6,14 @@ require "json"
 
 module Prauga
   module FlexDoc
+    # Framework-neutral FlexDoc host serving the HTML shell and packaged renderer assets.
     class Host
       IMMUTABLE_CACHE = "public, max-age=31536000, immutable"
 
       attr_reader :config, :fingerprint
 
+      # @param config [Config] renderer and route settings
+      # @param assets_dir [String, nil] optional directory overriding bundled renderer assets
       def initialize(config = Config.new, assets_dir: nil)
         @config = config
         root = assets_dir || File.expand_path("../../../assets", __dir__)
@@ -19,6 +22,10 @@ module Prauga
         @fingerprint = Digest::SHA256.hexdigest(@javascript + "\0" + @css)[0, 16]
       end
 
+      # Match a request path and return the docs shell, renderer asset, or 404 response.
+      #
+      # @param path [String] request path
+      # @return [Response]
       def response_for_path(path)
         return documentation if path == config.path || path == "#{config.path}/"
         return renderer_javascript if path == "#{config.path}/__flexdoc/renderer.js"
@@ -27,6 +34,9 @@ module Prauga
         Response.new(status: 404, content_type: "text/plain; charset=utf-8", body: "Not Found", cache_control: nil)
       end
 
+      # Build the HTML docs shell response.
+      #
+      # @return [Response]
       def documentation
         try_it = { enabled: config.try_it_enabled }
         try_it[:defaultServer] = config.try_it_default_server unless config.try_it_default_server.nil?
@@ -57,10 +67,16 @@ module Prauga
         Response.new(status: 200, content_type: "text/html; charset=utf-8", body:, cache_control: "no-cache")
       end
 
+      # Return the packaged renderer JavaScript asset.
+      #
+      # @return [Response]
       def renderer_javascript
         Response.new(status: 200, content_type: "application/javascript; charset=utf-8", body: @javascript, cache_control: IMMUTABLE_CACHE)
       end
 
+      # Return the packaged renderer CSS asset.
+      #
+      # @return [Response]
       def renderer_css
         Response.new(status: 200, content_type: "text/css; charset=utf-8", body: @css, cache_control: IMMUTABLE_CACHE)
       end

data/lib/prauga/flexdoc/rack_app.rb

@@ -2,11 +2,17 @@
 
 module Prauga
   module FlexDoc
+    # Rack application that serves FlexDoc routes from a {Host}.
     class RackApp
+      # @param host [Host] host backing the Rack application
       def initialize(host = Host.new)
         @host = host
       end
 
+      # Rack entrypoint.
+      #
+      # @param env [Hash] Rack environment
+      # @return [Array]
       def call(env)
         path = "#{env.fetch("SCRIPT_NAME", "")}#{env.fetch("PATH_INFO", "")}"
         @host.response_for_path(path).rack

data/lib/prauga/flexdoc/rails.rb

@@ -2,9 +2,18 @@
 
 module Prauga
   module FlexDoc
+    # Rails routing helpers for mounting {RackApp}.
     module Rails
       module_function
 
+      # Mount FlexDoc beneath a Rails router.
+      #
+      # @param mapper [#mount] Rails route mapper, typically `self` inside `routes.rb`
+      # @param host [Host] configured FlexDoc host
+      # @param at [String, nil] mount path; defaults to `host.config.path`
+      # @param as [Symbol] Rails mount name
+      # @return [Host] the mounted host
+      # @raise [ArgumentError] when `at` does not match `host.config.path`
       def mount(mapper, host: Host.new, at: nil, as: :flexdoc)
         mount_path = at || host.config.path
         normalized_mount_path = Config.new(path: mount_path).path

data/lib/prauga/flexdoc/response.rb

@@ -2,7 +2,9 @@
 
 module Prauga
   module FlexDoc
+    # HTTP response produced by {Host}.
     Response = Data.define(:status, :content_type, :body, :cache_control) do
+      # @return [Hash{String => String}] Rack-compatible response headers.
       def headers
         result = {
           "content-type" => content_type,
@@ -12,6 +14,7 @@ module Prauga
         result
       end
 
+      # @return [Array(Integer, Hash{String => String}, Array<String>)] Rack triplet.
       def rack
         [status, headers, [body]]
       end

data/lib/prauga/flexdoc/version.rb

@@ -2,6 +2,6 @@
 
 module Prauga
   module FlexDoc
-    VERSION = "0.4.1"
+    VERSION = "0.4.2"
   end
 end

data/lib/prauga/flexdoc.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# Self-hosted FlexDoc integration for Rack and Rails applications.
+#
+# Require this file to load {Prauga::FlexDoc::Host}, {Prauga::FlexDoc::RackApp},
+# {Prauga::FlexDoc::Config}, and the Rails mount helper.
+
 require_relative "flexdoc/version"
 require_relative "flexdoc/config"
 require_relative "flexdoc/response"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prauga-flexdoc
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Prauga
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-06 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack