spec_forge 0.6.0 → 0.7.0

data/lib/spec_forge/documentation/openapi/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      #
+      # Base class for OpenAPI documentation objects
+      #
+      # Provides common functionality for OpenAPI specification objects
+      # like operations, responses, and schemas.
+      #
+      class Base
+        #
+        # The document object containing structured API data
+        #
+        # @return [Object] The document with endpoint information
+        #
+        attr_reader :document
+
+        #
+        # Creates a new OpenAPI base object
+        #
+        # @param document [Object] The document object containing API data
+        #
+        # @return [Base] A new base instance
+        #
+        def initialize(document)
+          @document = document
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/openapi/v3_0/example.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+        #
+        # Represents an OpenAPI 3.0 Example object
+        #
+        # Creates example objects for request/response documentation with
+        # optional summary, description, and external reference support.
+        #
+        # @see https://spec.openapis.org/oas/v3.0.4.html#example-object
+        #
+        class Example < Data.define(:summary, :description, :value, :external_value)
+          #
+          # Creates a new OpenAPI example object
+          #
+          # @param summary [String, nil] Brief summary of the example's purpose
+          # @param description [String, nil] Detailed description of the example
+          # @param value [Object, nil] The actual example value
+          # @param external_value [String, nil] URL pointing to the example value
+          #
+          # @return [Example] A new example instance
+          #
+          def initialize(summary: nil, description: nil, value: nil, external_value: nil)
+            super
+          end
+
+          #
+          # Converts the example to an OpenAPI-compliant hash
+          #
+          # @return [Hash] OpenAPI-formatted example object
+          #
+          def to_h
+            super
+              .rename_key_unordered!(:external_value, :externalValue)
+              .compact_blank!
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/openapi/v3_0/media_type.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+        #
+        # Represents an OpenAPI 3.0 Media Type object
+        #
+        # Handles media type definitions for request and response bodies,
+        # including schema definitions, examples, and encoding information.
+        #
+        # @see https://spec.openapis.org/oas/v3.0.4.html#media-type-object
+        #
+        class MediaType < Data.define(:schema, :example, :examples, :encoding)
+          #
+          # Creates a new OpenAPI media type object
+          #
+          # @param schema [Hash, nil] Schema definition for the media type
+          # @param example [Object, nil] Single example value
+          # @param examples [Hash, nil] Multiple named examples
+          # @param encoding [Hash, nil] Encoding information for the media type
+          #
+          # @return [MediaType] A new media type instance
+          #
+          def initialize(schema: nil, example: nil, examples: nil, encoding: nil)
+            super
+          end
+
+          #
+          # Converts the media type to an OpenAPI-compliant hash
+          #
+          # @return [Hash] OpenAPI-formatted media type object
+          #
+          def to_h
+            super.compact_blank!
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/openapi/v3_0/operation.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+        #
+        # Represents an OpenAPI 3.0 Operation object
+        #
+        # Handles the complete definition of API operations including parameters,
+        # request bodies, responses, and security requirements for OpenAPI specs.
+        #
+        # @see https://spec.openapis.org/oas/v3.0.4.html#operation-object
+        #
+        class Operation < OpenAPI::Base
+          #
+          # Converts the operation to an OpenAPI-compliant hash
+          #
+          # Builds the complete operation object with all required and optional
+          # fields properly formatted for OpenAPI specification.
+          #
+          # @return [Hash] OpenAPI-formatted operation object
+          #
+          def to_h
+            {
+              # Required
+              responses:,
+              security:
+            }.merge_compact(
+              # All optional
+              tags:,
+              summary:,
+              description:,
+              operationId:,
+              parameters:,
+              requestBody:
+            )
+          end
+
+          #
+          # Returns the operation's unique identifier
+          #
+          # @return [String] The operation ID
+          #
+          def id
+            # The object ID is added to make every ID unique
+            document.id.to_camelcase(:lower) + object_id.to_s
+          end
+
+          alias_method :operationId, :id
+
+          #
+          # Returns a human-readable summary of the operation
+          #
+          # @return [String, nil] Brief operation summary
+          #
+          def summary
+            document.id.humanize
+          end
+
+          #
+          # Returns detailed description of the operation
+          #
+          # @return [String] Detailed operation description
+          #
+          def description
+            document.description
+          end
+
+          #
+          # Returns security requirements for the operation
+          #
+          # @return [Array] Array of security requirement objects
+          #
+          def security
+            # User defined
+            []
+          end
+
+          #
+          # Returns tags for categorizing the operation
+          #
+          # @return [Array] Array of tag names
+          #
+          def tags
+            # User defined
+            []
+          end
+
+          #
+          # Returns parameter definitions for the operation
+          #
+          # Transforms document parameters into OpenAPI parameter objects
+          # with proper schema types and location information.
+          #
+          # @return [Array] Array of parameter objects
+          #
+          def parameters
+            document.parameters.values.map do |parameter|
+              schema = Schema.new(type: parameter.type).to_h
+
+              {
+                schema:,
+                name: parameter.name,
+                in: parameter.location,
+                required: parameter.location == "path" || false
+              }
+            end
+          end
+
+          #
+          # Returns request body definition for the operation
+          #
+          # Groups requests by content type and creates proper OpenAPI
+          # request body object with examples and schemas.
+          #
+          # @return [Hash, nil] Request body object
+          #
+          def request_body
+            requests = document.requests
+            return if requests.blank?
+
+            requests = requests.group_by(&:content_type)
+
+            content =
+              requests.transform_values do |grouped_requests|
+                media_type_from_requests(grouped_requests)
+              end
+
+            {
+              description: "",
+              content:
+            }
+          end
+
+          alias_method :requestBody, :request_body
+
+          #
+          # Returns response definitions for the operation
+          #
+          # Groups responses by status code and transforms them into
+          # OpenAPI response objects with proper formatting.
+          #
+          # @return [Hash] Hash mapping status codes to response objects
+          #
+          def responses
+            document.responses
+              .group_by(&:status)
+              .transform_values! do |responses|
+                response = responses.first
+                Response.new(response).to_h
+              end
+          end
+
+          private
+
+          def media_type_from_requests(requests)
+            request = requests.first
+            schema = Schema.new(type: request.type, content: request.content).to_h
+
+            examples =
+              requests.to_h do |request|
+                example_name = request.name.to_camelcase(:lower)
+                example = Example.new(summary: request.name, value: request.content).to_h
+
+                [example_name, example]
+              end
+
+            MediaType.new(schema:, examples:).to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/openapi/v3_0/response.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+        #
+        # Represents an OpenAPI 3.0 Response object
+        #
+        # Handles response definitions including status descriptions, content types,
+        # headers, and links for OpenAPI specifications.
+        #
+        # @see https://spec.openapis.org/oas/v3.0.4.html#response-object
+        #
+        class Response < OpenAPI::Base
+          #
+          # Converts the response to an OpenAPI-compliant hash
+          #
+          # Builds the complete response object with required description and
+          # optional content, headers, and links.
+          #
+          # @return [Hash] OpenAPI-formatted response object
+          #
+          def to_h
+            {
+              # Required
+              description: "",
+              content:
+            }.merge_compact(
+              # Optional
+              headers:
+            )
+          end
+
+          #
+          # Returns content definitions for the response
+          #
+          # Creates media type objects with schemas and merges with any
+          # documentation-provided content definitions.
+          #
+          # @return [Hash] Content definitions by media type
+          #
+          def content
+            schema = Schema.new(type: document.body.type).to_h
+
+            {
+              document.content_type => MediaType.new(schema:).to_h
+            }
+          end
+
+          #
+          # Returns header definitions for the response
+          #
+          # Merges document headers with documentation-provided headers.
+          #
+          # @return [Hash, nil] Header definitions
+          #
+          def headers
+            document.headers.presence
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/openapi/v3_0/schema.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+        #
+        # Represents an OpenAPI 3.0 Schema object
+        #
+        # Handles schema definitions for data types, converting internal type
+        # representations to OpenAPI-compliant schema objects.
+        #
+        # @see https://spec.openapis.org/oas/v3.0.4.html#schema-object
+        #
+        class Schema
+          #
+          # The schema type (string, integer, object, etc.)
+          #
+          # @return [String, nil] The OpenAPI schema type
+          #
+          attr_reader :type
+
+          #
+          # The schema format (date-time, int64, etc.)
+          #
+          # @return [String, nil] The OpenAPI schema format
+          #
+          attr_reader :format
+
+          #
+          # Creates a new OpenAPI schema object
+          #
+          # @param options [Hash] Schema configuration options
+          # @option options [String] :type The data type to convert to OpenAPI format
+          #
+          # @return [Schema] A new schema instance
+          #
+          def initialize(options = {})
+            @type, @format = transform_type(options[:type])
+          end
+
+          #
+          # Converts the schema to an OpenAPI-compliant hash
+          #
+          # @return [Hash] OpenAPI-formatted schema object
+          #
+          def to_h
+            {
+              type:,
+              format:
+            }.compact_blank!
+          end
+
+          private
+
+          def transform_type(format)
+            case format
+            when "datetime", "time"
+              ["string", "date-time"]
+            when "int64", "i64"
+              ["integer", "int64"]
+            when "int32", "i32"
+              ["integer", "int32"]
+            when "double", "float"
+              ["number", format]
+            when "object"
+              ["object"]
+            when "array"
+              ["array"]
+            when "boolean", "number", "integer", "string"
+              [format]
+            else
+              ["string", format]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/openapi/v3_0/tag.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+        #
+        # Represents an OpenAPI 3.0 Tag object
+        #
+        # Handles tag definitions for categorizing and organizing API operations
+        # with optional descriptions and external documentation links.
+        #
+        # @see https://spec.openapis.org/oas/v3.0.4.html#tag-object
+        #
+        class Tag < Data.define(:name, :description, :external_docs)
+          #
+          # Creates a tag object from name and data
+          #
+          # Handles both string descriptions and hash configurations with
+          # external documentation references.
+          #
+          # @param name [String, Symbol] The tag name
+          # @param data [String, Hash] Either a description string or full config hash
+          #
+          # @return [Tag] A new tag instance
+          #
+          def self.parse(name, data)
+            name = name.to_s
+
+            case data
+            when String
+              description = data
+            when Hash
+              description = data[:description]
+              external_docs = data[:external_docs]
+            end
+
+            new(name:, description:, external_docs:)
+          end
+
+          #
+          # Creates a new OpenAPI tag object
+          #
+          # @param name [String] The tag name
+          # @param description [String, nil] Optional tag description
+          # @param external_docs [Hash, nil] Optional external documentation reference
+          #
+          # @return [Tag] A new tag instance
+          #
+          def initialize(name:, description: nil, external_docs: nil)
+            super
+          end
+
+          #
+          # Converts the tag to an OpenAPI-compliant hash
+          #
+          # Transforms internal attribute names to match OpenAPI specification
+          # and removes any blank values for clean output.
+          #
+          # @return [Hash] OpenAPI-formatted tag object
+          #
+          def to_h
+            super
+              .rename_key_unordered!(:external_docs, :externalDocs)
+              .compact_blank!
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/openapi.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    #
+    # OpenAPI documentation generation functionality
+    #
+    # Contains classes and modules for generating OpenAPI specifications
+    # from SpecForge test data. Supports multiple OpenAPI versions.
+    #
+    module OpenAPI
+    end
+  end
+end
+
+require_relative "openapi/base"
+
+require_relative "openapi/v3_0/example"
+require_relative "openapi/v3_0/media_type"
+require_relative "openapi/v3_0/operation"
+require_relative "openapi/v3_0/response"
+require_relative "openapi/v3_0/schema"
+require_relative "openapi/v3_0/tag"

data/lib/spec_forge/documentation.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # API documentation generation functionality
+  #
+  # This module provides tools for extracting API documentation from SpecForge
+  # test files and generating various output formats like OpenAPI specifications.
+  # It handles the complete pipeline from test execution to documentation rendering.
+  #
+  # @example Generating OpenAPI documentation
+  #   # From CLI
+  #   spec_forge docs generate
+  #
+  #   # Programmatically
+  #   document = Documentation::Loader.load_document
+  #   spec = Documentation::Generators::OpenAPI["3.0"].new(document).generate
+  #
+  module Documentation
+  end
+end
+
+require_relative "documentation/builder"
+require_relative "documentation/document"
+require_relative "documentation/loader"
+require_relative "documentation/openapi"
+require_relative "documentation/generators"

data/lib/spec_forge/error.rb

@@ -300,5 +300,22 @@ module SpecForge
         super(message)
       end
     end
+
+    #
+    # Raised when an OpenAPI specification fails validation
+    #
+    # This error indicates that the generated OpenAPI document contains
+    # validation errors according to the OpenAPI specification standards.
+    # It's typically raised after attempting to validate a generated specification.
+    #
+    # @example
+    #   begin
+    #     generator.validate!(openapi_spec)
+    #   rescue SpecForge::Error::InvalidOASDocument
+    #     puts "Generated specification has validation errors"
+    #   end
+    #
+    class InvalidOASDocument < Error
+    end
   end
 end

data/lib/spec_forge/factory.rb

@@ -33,7 +33,7 @@ module SpecForge
       factories = []
 
       Dir[path].each do |file_path|
-        hash = YAML.load_file(file_path).deep_symbolize_keys
+        hash = YAML.load_file(file_path, symbolize_names: true)
 
         hash.each do |factory_name, factory_hash|
           factory_hash[:name] = factory_name
@@ -72,7 +72,7 @@ module SpecForge
     #
     def initialize(name:, **input)
       @name = name
-      input = Normalizer.normalize_factory!(input)
+      input = Normalizer.normalize!(input, using: :factory)
 
       @input = input
       @model_class = input[:model_class]

data/lib/spec_forge/filter.rb

@@ -22,7 +22,7 @@ module SpecForge
       # @param expectation_name [String, nil] Optional expectation name that was used by the filter
       #
       def announce(forges, file_name:, spec_name:, expectation_name:)
-        filters = {file_name:, spec_name:, expectation_name:}.reject { |k, v| v.blank? }
+        filters = {file_name:, spec_name:, expectation_name:}.compact_blank
         return if filters.size == 0
 
         filters_display = filters.join_map(", ") { |k, v| "#{k.in_quotes} => #{v.in_quotes}" }
@@ -69,10 +69,9 @@ module SpecForge
             # Expectation filter
             next spec unless expectation_name
 
-            expectations = spec.expectations.select { |e| e.name == expectation_name }
-            next if expectations.empty?
+            spec.expectations.select! { |e| e.name == expectation_name }
+            next if spec.expectations.empty?
 
-            spec.expectations = expectations
             spec
           end
 

data/lib/spec_forge/forge.rb

@@ -117,8 +117,7 @@ module SpecForge
       # }
       #
       specs.each_with_object({}) do |spec, hash|
-        overlay = spec[:expectations].to_h { |e| [e[:id], e.delete(:variables)] }
-          .reject { |_k, v| v.blank? }
+        overlay = spec[:expectations].to_h { |e| [e[:id], e.delete(:variables)] }.compact_blank
 
         hash[spec[:id]] = {base: spec.delete(:variables), overlay:}
       end
@@ -153,13 +152,15 @@ module SpecForge
         overlay = spec[:expectations].to_h do |expectation|
           [
             expectation[:id],
-            expectation.extract!(*HTTP::REQUEST_ATTRIBUTES).reject { |_k, v| v.blank? }
+            expectation.extract!(*HTTP::REQUEST_ATTRIBUTES).compact_blank
           ]
         end
 
-        overlay.reject! { |_k, v| v.blank? }
+        overlay.compact_blank!
 
         base = spec.extract!(*HTTP::REQUEST_ATTRIBUTES)
+        base.compact_blank!
+
         base = config.deep_merge(base)
         base[:http_verb] ||= "GET"
 

data/lib/spec_forge/http/backend.rb

@@ -144,6 +144,8 @@ module SpecForge
       #
       def update_request(request, headers, query, body)
         request.headers.merge!(headers)
+        request.headers.transform_values!(&:to_s)
+
         request.params.merge!(query)
         request.body = body.to_json
       end