docit 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85a7407aab5a5fea2aa0c679d469360f124884ebeac2e4479265cbcdd818210d
-  data.tar.gz: c946eea9c5a664931630b00726f33b8e5bb296c1493e799c67cd905f330cba1d
+  metadata.gz: 7fbb7845b4244fcde9b80e6702c17bf6c1e64274b3dada27a7b5a021929819d8
+  data.tar.gz: 21c9ab47ab7c6d5423ed965a57297594093590e916b94addc3a446fd58799c1e
 SHA512:
-  metadata.gz: 3dd0a62c6d0f138916839a7bcc445f98921abaf9e0ef477473e4dddba67f2033fd29ffb51a4803597d98f0807ee24c53d6b5a90a8d144d87c54669ee51155fef
-  data.tar.gz: d953ceef06cd91034fa79503a07da386dcefc7cdddabcb3567d1638d6546a2c484bdebd82f263d732a94b89447a9e9f6b659d7008c322d2e238e002aca286a1b
+  metadata.gz: e809ab547345f748550f1545f52b87ed2b46f7d4aebda3cd96807d27eae4ff451f5d149d3bdc227a3b8aa6f9bfa8183d3ad234f8f7e216c0c5e5c9a648cf6566
+  data.tar.gz: bf6f544ac536d88a42a1256670c257cbc3d0a2cc8425057042a5930315f65a07af5ecb3b45aec75d87178ca2ca909ba4c6a51d05e74b2e35389b981fad858a55

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [0.7.0] - 2026-06-21
+
+### Added
+- `config.default_security :scheme`: apply a security requirement to every endpoint by default, for APIs that are authenticated by default. Emits a top-level OpenAPI `security` so you no longer repeat `security` on each doc block
+- `security :none` in a doc block: opt an endpoint out of the default (emits an empty `security` array, e.g. for public endpoints)
+
+### Changed
+- The System Map's JavaScript and CSS now live in real asset files (`lib/docit/ui/assets/system.js` and `system.css`) read at load time, instead of large Ruby heredocs — same rendered output, easier to maintain
+
+## [0.6.0] - 2026-06-20
+
+### Added
+- Property options for richer schemas: `default`, `nullable`, `read_only`, and `write_only` on any `property` in a request body, response, or shared schema — emitted as OpenAPI `default`, `nullable`, `readOnly`, and `writeOnly`. Falsy values like `default: false` and `default: 0` are preserved
+- Response headers: declare them inside a `response` block with `header "X-RateLimit-Remaining", type: :integer, description: "..."`, emitted as an OpenAPI `headers` object on that response
+- System Map `uses_schema` edges: documented endpoints that reference a shared schema (`schema ref: :User`) are now linked to that schema node in the graph
+- `TROUBLESHOOTING.md` covering common questions (missing routes, ignored options, AI setup, production exposure)
+- README section on restricting access to the docs endpoints in production
+
+### Changed
+- README documents the new property options and response headers
+
+### Removed
+- The AI "Explain section" / system insights feature and its endpoint (`/api-docs/system/insights`). It was unauthenticated — exposing an outbound, billable AI call and rendering AI output without escaping — so it has been removed. The rest of the System Map (diagram, docs view, search, theming, PNG export) is unchanged, and `rails docit:autodoc` is unaffected
+
 ## [0.5.0] - 2026-05-31
 
 ### Added

data/README.md

@@ -27,6 +27,8 @@ Decorator-style API documentation for Ruby on Rails. Write OpenAPI 3.0.3 docs wi
   - [Request bodies](#request-bodies)
   - [Path parameters](#path-parameters)
   - [Enums](#enums)
+  - [Property options](#property-options)
+  - [Response headers](#response-headers)
   - [Security](#security)
   - [Deprecated endpoints](#deprecated-endpoints)
   - [Nested objects and arrays](#nested-objects-and-arrays)
@@ -44,12 +46,14 @@ Decorator-style API documentation for Ruby on Rails. Write OpenAPI 3.0.3 docs wi
   - [System Map](#system-map)
   - [How it works](#how-it-works)
   - [Mounting at a different path](#mounting-at-a-different-path)
+  - [Restricting access in production](#restricting-access-in-production)
   - [JSON spec only](#json-spec-only)
   - [Development](#development)
   - [Contributing](#contributing)
   - [License](#license)
 - Project docs
   - [CHANGELOG](CHANGELOG.md)
+  - [TROUBLESHOOTING](TROUBLESHOOTING.md)
   - [CONTRIBUTING](CONTRIBUTING.md)
   - [CODE OF CONDUCT](CODE_OF_CONDUCT.md)
 
@@ -302,6 +306,37 @@ doc_for :index do
 end
 ```
 
+### Property options
+
+Any `property` (in a request body, response, or shared schema) accepts these OpenAPI 3.0.3 options:
+
+```ruby
+request_body required: true do
+  property :id,       type: :integer, read_only: true        # readOnly: present in responses, not accepted as input
+  property :password, type: :string,  write_only: true       # writeOnly: accepted as input, never returned
+  property :role,     type: :string,  default: "member"      # default value
+  property :nickname, type: :string,  nullable: true         # may be null
+  property :active,   type: :boolean, default: false         # falsy defaults are preserved
+end
+```
+
+These map to `readOnly`, `writeOnly`, `default`, and `nullable` in the generated spec.
+
+### Response headers
+
+Document the headers a response returns with `header` inside a `response` block:
+
+```ruby
+response 200, "Orders list" do
+  header "X-Total-Count", type: :integer, description: "Total orders available"
+  header "X-RateLimit-Remaining", type: :integer, description: "Requests left in the window"
+
+  property :orders, type: :array do
+    property :id, type: :integer
+  end
+end
+```
+
 ### Security
 
 Mark endpoints as requiring authentication:
@@ -317,6 +352,28 @@ doc_for :destroy do
 end
 ```
 
+#### Default (global) security
+
+If most of your API is authenticated, declare the requirement once instead of on every endpoint. In your initializer:
+
+```ruby
+config.auth :api_key, name: "session", location: "query"
+config.default_security :api_key   # applies to every endpoint
+```
+
+Then mark only the **public** endpoints as exceptions with `security :none`:
+
+```ruby
+doc_for :index do
+  summary "List banks"
+  tags "Banks"
+  security :none             # public — opts out of the default
+  response 200, "OK"
+end
+```
+
+An explicit `security :scheme` on an endpoint still overrides the default.
+
 ### Deprecated endpoints
 
 ```ruby
@@ -533,6 +590,34 @@ In `config/routes.rb`:
 mount Docit::Engine => "/docs"        # now at /docs instead of /api-docs
 ```
 
+## Restricting access in production
+
+The Docit endpoints (`/api-docs`, `/api-docs/spec`, `/api-docs/system`, `/api-docs/system.json`) are **unauthenticated by default** and expose your full API surface, the OpenAPI spec, and — for the System Map — your app's structure and source file paths. That is convenient in development, but in production you almost always want to gate them.
+
+Mount the engine inside an authenticated constraint, or behind whatever auth your app already uses:
+
+```ruby
+# config/routes.rb
+
+# Option A — only mount outside production
+mount Docit::Engine => "/api-docs" unless Rails.env.production?
+
+# Option B — gate behind an authenticated constraint (e.g. Devise admins)
+authenticate :user, ->(u) { u.admin? } do
+  mount Docit::Engine => "/api-docs"
+end
+
+# Option C — HTTP Basic auth via a Rack constraint
+admins_only = ->(request) do
+  ActiveSupport::SecurityUtils.secure_compare(
+    request.authorization.to_s, ENV.fetch("DOCS_AUTH", "")
+  )
+end
+constraints(admins_only) { mount Docit::Engine => "/api-docs" }
+```
+
+If you disable the System Map specifically, set `config.system_graph_enabled = false` — `/api-docs/system.json` then returns `404`.
+
 ## JSON spec only
 
 If you just want the raw OpenAPI JSON (e.g., for code generation):

data/TROUBLESHOOTING.md

@@ -0,0 +1,57 @@
+# Troubleshooting
+
+Common questions and fixes when working with Docit.
+
+## My route isn't showing up in the spec
+
+Docit only documents an endpoint if **both** are true:
+
+1. The route exists in `config/routes.rb` (visible in `rails routes`).
+2. A doc is registered for that controller + action — either inline with `doc_for :action do ... end` or via `use_docs SomeDocs`.
+
+A route with no matching `doc_for`/`use_docs` is simply absent from `/api-docs/spec`. It will still appear on the **System Map** (`/api-docs/system`) marked `undocumented`, which is the quickest way to see your coverage gaps.
+
+Checklist:
+
+- Is the action name spelled exactly the same in the route and in `doc_for`?
+- Is the controller actually loaded? Docit eager-loads controllers when generating the spec, but a controller in a non-standard path may be missed.
+- If using `use_docs`, does the doc module define a `doc :action` block for that action?
+
+## A doc_for option seems to be ignored
+
+Docit's DSL methods are explicit. If you mistype one (e.g. `summmary` instead of `summary`), the call currently does nothing rather than raising — so the option silently disappears.
+
+Double-check the spelling of DSL methods against the [DSL reference in the README](README.md). The supported response/property options include `summary`, `description`, `tags`, `response`, `request_body`, `parameter`, `property` (with `type`, `format`, `example`, `enum`, `default`, `nullable`, `read_only`, `write_only`), `header`, `schema ref:`, `security`, `deprecated`, and `operation_id`.
+
+## A System Map section says "undocumented" or shows low coverage
+
+That section's endpoints have no registered docs. Add `doc_for`/`use_docs` for those actions, or accept the gap — coverage is informational, not an error.
+
+## Schemas aren't linked on the System Map
+
+`uses_schema` edges only appear when a documented endpoint references a shared schema with `schema ref: :Name` (in its request body or a response), and that schema is defined with `Docit.define_schema :Name`. A plain inline `property` block does not create a schema node.
+
+## I documented an action twice and my changes are ignored
+
+Docit's registry keeps the **first** doc registered for a given controller + action and ignores later ones. So if an action is already documented (e.g. via `use_docs SomeDocs`) and you also add an inline `doc_for :same_action do ... end`, the inline block is silently dropped — the `use_docs` version wins.
+
+Document each action in exactly one place. If you need to override a shared doc module for one action, change it in the module rather than re-declaring it on the controller.
+
+## AI autodoc / scaffolding isn't working
+
+- Run `rails generate docit:ai_setup` once to configure a provider (OpenAI, Anthropic, or Groq). The key is written to `.docit_ai.yml`, which the generator adds to `.gitignore` — **never commit it.**
+- `rails docit:autodoc` sends controller **source code** to your configured provider. In an interactive terminal it asks for confirmation first; in a non-interactive context (CI, piping) it proceeds without prompting, so only run it where sending source is acceptable.
+- Preview without writing files: `DRY_RUN=1 rails docit:autodoc`.
+- Rate-limit / 429 errors are retried with backoff automatically; a persistent failure usually means an invalid key or an unsupported model name.
+
+## The System Map or docs pages are exposed in production
+
+The Docit endpoints are **unauthenticated by default**. They expose your API surface, the OpenAPI spec, and your app structure. In production, gate the engine — see [Restricting access in production](README.md#restricting-access-in-production) in the README. To disable the System Map specifically, set `config.system_graph_enabled = false`.
+
+## Spec generation is slow on a large app
+
+Generating the spec eager-loads controllers and walks every route. For very large apps this is a one-time cost per request; put the docs behind a cache or a non-production-only mount if it matters. The System Map graph is rebuilt per request — if that becomes a bottleneck, mount it behind auth and access it sparingly.
+
+## Still stuck?
+
+Open an issue at <https://github.com/S13G/docit/issues> with your Docit version, Rails version, and a minimal `doc_for` / route example.

data/app/controllers/docit/ui_controller.rb

@@ -21,26 +21,12 @@ module Docit
     end
 
     def system_spec
-      unless Docit.configuration.system_graph_enabled
-        return render(json: { error: "System graph disabled" }, status: :not_found)
-      end
+      return render(json: { error: "System graph disabled" }, status: :not_found) unless Docit.configuration.system_graph_enabled
 
       RouteInspector.eager_load_controllers!
       render json: SystemGraph::Generator.generate
     end
 
-    def system_insights
-      graph = system_graph
-      insight = Ai::SystemInsightGenerator.new(
-        graph: graph,
-        selected_node_ids: selected_node_ids,
-        mode: insight_mode
-      ).generate
-      render json: { insight: insight }
-    rescue Docit::Error => e
-      render json: { error: e.message }, status: :unprocessable_entity
-    end
-
     def spec
       RouteInspector.eager_load_controllers!
       render json: SchemaGenerator.generate
@@ -58,27 +44,11 @@ module Docit
       renderer = RENDERERS.fetch(ui_name).new(
         spec_url: spec_url,
         system_url: system_url,
-        system_insights_url: system_insights_url,
         nav_paths: nav_paths
       )
       render html: renderer.render.html_safe, layout: false
     end
 
-    def system_graph
-      RouteInspector.eager_load_controllers!
-      SystemGraph::Generator.generate
-    end
-
-    def selected_node_ids
-      params.fetch(:node_ids, "").to_s.split(",").reject(&:empty?)
-    end
-
-    # Validate at the boundary: only the known modes are honored, anything
-    # else falls back to the safe per-node default.
-    def insight_mode
-      params[:mode].to_s == "section" ? :section : :nodes
-    end
-
     def spec_url
       "#{request.base_url}#{Docit::Engine.routes.url_helpers.spec_path}"
     end
@@ -87,10 +57,6 @@ module Docit
       "#{request.base_url}#{Docit::Engine.routes.url_helpers.system_spec_path}"
     end
 
-    def system_insights_url
-      "#{request.base_url}#{Docit::Engine.routes.url_helpers.system_insights_path}"
-    end
-
     def nav_paths
       helpers = Docit::Engine.routes.url_helpers
       { swagger: helpers.swagger_path, scalar: helpers.scalar_path, system: helpers.system_path }

data/config/routes.rb

@@ -5,7 +5,6 @@ Docit::Engine.routes.draw do
   get "swagger", to: "ui#swagger"
   get "scalar", to: "ui#scalar"
   get "system.json", to: "ui#system_spec", defaults: { format: :json }, as: :system_spec
-  get "system/insights", to: "ui#system_insights", defaults: { format: :json }, as: :system_insights
   get "system", to: "ui#system", as: :system
   get "spec", to: "ui#spec", defaults: { format: :json }
 end

data/lib/docit/ai/autodoc_runner.rb

@@ -57,9 +57,7 @@ module Docit
         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
+        raise Docit::Error, "Docit is not installed. Run: rails generate docit:install" if File.exist?(initializer) == false
 
         routes_file = Rails.root.join("config", "routes.rb")
         return unless File.exist?(routes_file) && !File.read(routes_file).include?("Docit::Engine")
@@ -179,8 +177,15 @@ module Docit
           end
         end
 
+        endpoints = pluralize(@results[:generated], "endpoint")
+        files = pluralize(@results[:files].length, "file")
         @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}."
+        @output.puts "Generated docs for #{endpoints} in #{files}."
+      end
+
+      # "1 endpoint" / "2 endpoints" — keeps the summary lines short and readable.
+      def pluralize(count, noun)
+        "#{count} #{noun}#{"s" unless count == 1}"
       end
 
       def inject_tags(generated)

data/lib/docit/ai/doc_writer.rb

@@ -20,7 +20,7 @@ module Docit
       end
 
       def doc_module_name
-        @controller_name.delete_suffix("Controller").gsub("::", "::") + "Docs"
+        "#{@controller_name.delete_suffix("Controller").gsub("::", "::")}Docs"
       end
 
       def file_exists?
@@ -44,7 +44,7 @@ module Docit
         match = content.match(class_pattern)
         return false if match.nil?
 
-        indent = match[1][/^\s*/] + "  "
+        indent = "#{match[1][/^\s*/]}  "
         use_docs_line = "#{indent}use_docs #{doc_module_name}\n"
         content = content.sub(class_pattern, "\\1\n#{use_docs_line}")
 
@@ -100,7 +100,7 @@ module Docit
           lines << "#{"  " * (@module_parts.length - 1 - i)}end"
         end
 
-        lines.join("\n") + "\n"
+        "#{lines.join("\n")}\n"
       end
 
       def indent_block(block, depth)

data/lib/docit/ai/groq_client.rb

@@ -59,18 +59,14 @@ module Docit
 
       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
+        if (header = response["Retry-After"]) && header.to_f.positive?
+          return header.to_f
         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
+        return (Regexp.last_match(1).to_i * 60) + Regexp.last_match(2).to_f if message =~ /(\d+)m([\d.]+)s/
 
-        if message =~ /([\d.]+)s/
-          return Regexp.last_match(1).to_f
-        end
+        return Regexp.last_match(1).to_f if message =~ /([\d.]+)s/
 
         nil
       end

data/lib/docit/ai/scaffold_generator.rb

@@ -50,8 +50,10 @@ module Docit
 
         inject_tags(grouped)
 
+        endpoints = "endpoint".pluralize(gaps.length)
+        files = "file".pluralize(@files_written.length)
         @output.puts ""
-        @output.puts "Scaffolded #{gaps.length} endpoint#{"s" if gaps.length > 1} in #{@files_written.length} file#{"s" if @files_written.length > 1}."
+        @output.puts "Scaffolded #{gaps.length} #{endpoints} in #{@files_written.length} #{files}."
         @output.puts "Fill in the TODO placeholders in your doc files."
         @files_written
       end

data/lib/docit/ai/tag_injector.rb

@@ -24,7 +24,7 @@ module Docit
         insertion_point = find_insertion_point(content)
         return [] if insertion_point.nil?
 
-        content = content.insert(insertion_point, "\n#{lines.join("\n")}")
+        content.insert(insertion_point, "\n#{lines.join("\n")}")
         File.write(initializer_path, content)
 
         new_tags

data/lib/docit/ai.rb

@@ -12,4 +12,3 @@ require_relative "ai/doc_writer"
 require_relative "ai/tag_injector"
 require_relative "ai/autodoc_runner"
 require_relative "ai/scaffold_generator"
-require_relative "ai/system_insight_generator"

data/lib/docit/builders/response_builder.rb

@@ -3,15 +3,16 @@
 module Docit
   module Builders
     # Builds the schema for a single HTTP response, including properties,
-    # examples, and schema references.
+    # examples, headers, and schema references.
     class ResponseBuilder
-      attr_reader :status, :description, :properties, :examples, :schema_ref
+      attr_reader :status, :description, :properties, :examples, :headers, :schema_ref
 
       def initialize(status:, description:)
         @status = status
         @description = description
         @properties = []
         @examples = []
+        @headers = []
         @schema_ref = nil
       end
 
@@ -19,6 +20,15 @@ module Docit
         @schema_ref = ref.to_sym
       end
 
+      # Declares a response header, e.g. a rate-limit or pagination header:
+      #   header "X-RateLimit-Remaining", type: :integer, description: "..."
+      def header(name, type: :string, description: nil, example: nil)
+        entry = { name: name.to_s, type: type.to_s }
+        entry[:description] = description if description
+        entry[:example] = example unless example.nil?
+        @headers << entry
+      end
+
       def property(name, type:, format: nil, example: nil, enum: nil, description: nil, items: nil, **opts, &block)
         prop = { name: name, type: type }
         prop[:format] = format if format

data/lib/docit/configuration.rb

@@ -18,6 +18,7 @@ module Docit
       @system_graph_excluded_paths = []
       @default_ui = :scalar
       @security_schemes = {}
+      @default_security = nil
       @tags = []
       @servers = []
       @license = nil
@@ -27,9 +28,7 @@ module Docit
 
     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
+      raise ArgumentError, "Unsupported UI: #{value}. Must be one of: #{SUPPORTED_UIS.join(", ")}" unless SUPPORTED_UIS.include?(ui)
 
       @default_ui = ui
     end
@@ -62,6 +61,17 @@ module Docit
       @security_schemes.dup
     end
 
+    # Apply one or more security schemes to every endpoint by default. Individual
+    # endpoints opt out with `security :none` in their doc block.
+    def default_security(*schemes)
+      @default_security = schemes.flatten.map(&:to_sym) unless schemes.empty?
+      @default_security
+    end
+
+    def default_security?
+      !@default_security.nil? && !@default_security.empty?
+    end
+
     def tag(name, description: nil)
       entry = { name: name.to_s }
       entry[:description] = description if description

data/lib/docit/schema_generator.rb

@@ -19,6 +19,10 @@ module Docit
         }
       }
 
+      # Top-level security applies to every operation unless an operation
+      # overrides it (a documented scheme, or `security :none` to opt out).
+      spec[:security] = config.default_security.map { |s| { s.to_s => [] } } if config.default_security?
+
       tag_defs = config.tags
       spec[:tags] = tag_defs if tag_defs.any?
 
@@ -78,11 +82,19 @@ module Docit
 
       result[:requestBody] = build_request_body(operation._request_body) if operation._request_body
       result[:deprecated] = true if operation._deprecated
-      result[:security] = operation._security.map { |s| { s.to_s => [] } } if operation._security.any?
+      security = build_operation_security(operation)
+      result[:security] = security unless security.nil?
 
       result
     end
 
+    def build_operation_security(operation)
+      return nil if operation._security.empty?
+      return [] if operation._security.map(&:to_sym) == [:none]
+
+      operation._security.reject { |s| s.to_sym == :none }.map { |s| { s.to_s => [] } }
+    end
+
     def build_responses(response_builders)
       return { "200" => { description: "Success" } } if response_builders.empty?
 
@@ -104,10 +116,21 @@ module Docit
           entry[:content] = content
         end
 
+        entry[:headers] = build_response_headers(builder.headers) if builder.headers.any?
+
         hash[builder.status.to_s] = entry
       end
     end
 
+    def build_response_headers(headers)
+      headers.each_with_object({}) do |header, hash|
+        schema = { schema: { type: header[:type] } }
+        schema[:description] = header[:description] if header[:description]
+        schema[:schema][:example] = header[:example] if header.key?(:example)
+        hash[header[:name]] = schema
+      end
+    end
+
     def build_request_body(request_body_builder)
       if request_body_builder.schema_ref
         schema = { "$ref" => "#/components/schemas/#{request_body_builder.schema_ref}" }
@@ -138,43 +161,50 @@ module Docit
 
     def build_property_schema(prop)
       type = prop[:type].to_s
+      schema = base_property_schema(type, prop)
+
+      # These OpenAPI fields apply to any property shape, so set them once here
+      # rather than in each branch above. nil-checks let `false`/`0` through as
+      # explicit values (e.g. default: false), but skip unset options.
+      schema[:description] = prop[:description] if prop[:description]
+      schema[:example] = prop[:example] if prop[:example]
+      schema[:default] = prop[:default] unless prop[:default].nil?
+      schema[:nullable] = prop[:nullable] unless prop[:nullable].nil?
+      schema[:readOnly] = prop[:read_only] unless prop[:read_only].nil?
+      schema[:writeOnly] = prop[:write_only] unless prop[:write_only].nil?
+      schema
+    end
 
-      if type == "file"
-        schema = { type: "string", format: "binary" }
-        schema[:description] = prop[:description] if prop[:description]
-        schema
-      elsif type == "array"
-        schema = { type: "array" }
-        if prop[:children]
-          schema[:items] = {
-            type: "object",
-            properties: build_properties(prop[:children])
-          }
+    def base_property_schema(type, prop)
+      case type
+      when "file"
+        { type: "string", format: "binary" }
+      when "array"
+        { type: "array", items: array_items_schema(prop) }
+      else
+        # An object with declared children becomes a nested schema; everything
+        # else (including a childless "object") is a scalar with type/format/enum.
+        if type == "object" && prop[:children]
+          { type: "object", properties: build_properties(prop[:children]) }
         else
-          items_type = prop[:items]&.to_s || "string"
-          schema[:items] = { type: items_type }
+          scalar_property_schema(type, prop)
         end
-        schema[:description] = prop[:description] if prop[:description]
-        schema[:example] = prop[:example] if prop[:example]
-        schema
-      elsif type == "object" && prop[:children]
-        schema = {
-          type: "object",
-          properties: build_properties(prop[:children])
-        }
-        schema[:description] = prop[:description] if prop[:description]
-        schema[:example] = prop[:example] if prop[:example]
-        schema
-      else
-        schema = { type: type }
-        schema[:format] = prop[:format].to_s if prop[:format]
-        schema[:enum] = prop[:enum] if prop[:enum]
-        schema[:example] = prop[:example] if prop[:example]
-        schema[:description] = prop[:description] if prop[:description]
-        schema
       end
     end
 
+    def array_items_schema(prop)
+      return { type: "object", properties: build_properties(prop[:children]) } if prop[:children]
+
+      { type: prop[:items]&.to_s || "string" }
+    end
+
+    def scalar_property_schema(type, prop)
+      schema = { type: type }
+      schema[:format] = prop[:format].to_s if prop[:format]
+      schema[:enum] = prop[:enum] if prop[:enum]
+      schema
+    end
+
     def build_component_schemas
       Docit.schemas.each_with_object({}) do |(name, definition), hash|
         schema = {