Class: SpecForge::Documentation::Builder

Inherits:
Object
  • Object
show all
Defined in:
lib/spec_forge/documentation/builder.rb,
lib/spec_forge/documentation/builder/cache.rb,
lib/spec_forge/documentation/builder/compiler.rb,
lib/spec_forge/documentation/builder/extractor.rb

Overview

Builds API documentation by running blueprints and extracting endpoint data

The Builder orchestrates the documentation generation process by:

  1. Loading and running blueprint test files
  2. Capturing request/response data from successful test executions
  3. Compiling the raw data into a structured Document

It supports caching to avoid re-running tests when blueprints haven't changed.

Examples:

Creating a document from blueprints

document = Builder.create_document!(paths: "spec/blueprints/api.yml")

Using the builder directly for raw endpoint data

builder = Builder.new(paths: "spec/blueprints/api.yml")
endpoints = builder.endpoints

Defined Under Namespace

Classes: Cache, Compiler, Extractor

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(base_path: nil, paths: nil, verbosity_level: 0, use_cache: false) ⇒ Builder

Creates a new Builder instance

Parameters:

  • base_path (String, Pathname, nil) (defaults to: nil) —

    Base directory for blueprint files

  • paths (String, Pathname, nil) (defaults to: nil) —

    Specific blueprint file paths

  • verbosity_level (Integer) (defaults to: 0) —

    Output verbosity during test execution (0 = silent)

  • use_cache (Boolean) (defaults to: false) —

    Whether to use cached endpoint data if valid



56
57
58
59
60
61
62
63
 
# File 'lib/spec_forge/documentation/builder.rb', line 56

def initialize(base_path: nil, paths: nil, verbosity_level: 0, use_cache: false)
  @cache = Cache.new

  @base_path = base_path
  @paths = paths
  @use_cache = use_cache
  @verbosity_level = verbosity_level
end

Class Method Details

.create_document! ⇒ Document

Creates a complete Document from blueprint files

This is the primary entry point for generating documentation. It instantiates a Builder, extracts endpoints, compiles them, and returns a structured Document object.

Parameters:

  • base_path (Hash) —

    a customizable set of options

  • paths (Hash) —

    a customizable set of options

  • verbosity_level (Hash) —

    a customizable set of options

  • use_cache (Hash) —

    a customizable set of options

Returns:

  • (Document) —

    A structured document containing all API endpoints

Raises:



39
40
41
42
43
44
 
# File 'lib/spec_forge/documentation/builder.rb', line 39

def self.create_document!(**)
  endpoints = new(**).endpoints
  endpoints = Compiler.new(endpoints).compile

  Document.new(endpoints:)
end

Instance Method Details

#endpoints ⇒ Array<Hash>

Extracts endpoint data from blueprint test executions

Runs all blueprints and captures request/response data from each successful test step. Results are cached for subsequent calls when caching is enabled.

Returns:

  • (Array<Hash>) —

    Array of endpoint data hashes containing request and response information

Raises:



77
78
79
80
81
82
83
84
 
# File 'lib/spec_forge/documentation/builder.rb', line 77

def endpoints
  return @cache.read if @use_cache && @cache.valid?

  endpoints = capture_endpoint_data
  @cache.create(endpoints)

  endpoints
end