versponse 0.1.0 → 0.2.0

data/lib/versponse/object_schema.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Builds an object schema from properties; every unconditional property is required (no required keyword when none is)
+  #
+  # @api private
+  module ObjectSchema
+    # @param properties [Array<Versponse::Properties::Base>] properties in output order
+    # @param context [Versponse::SchemaContext] schema generation context
+    # @param description [String, nil] schema description
+    # @param schema_options [Hash] keywords merged last
+    # @param additional_properties [Boolean] additionalProperties (config.default_additional_properties, false for collapsed shapes)
+    # @return [Hash] object schema
+    def self.build(properties, context, description: nil, schema_options: {}, additional_properties: Versponse.configuration.default_additional_properties)
+      schema = {"type" => "object"}
+      schema["description"] = description if description
+      required = properties.reject(&:conditional?).map(&:key)
+      # OpenAPI 3.0 and draft 4 need at least one item in required
+      schema["required"] = required unless required.empty?
+      schema["properties"] = properties.to_h { |property| [property.key, property.schema(context)] }
+      schema["additionalProperties"] = additional_properties
+      schema.merge(schema_options)
+    end
+  end
+end

data/lib/versponse/open_api/builder.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Versponse
+  module OpenAPI
+    # Assembles one version of a document into a String-keyed Hash
+    #
+    # @api private
+    class Builder
+      # @param declarations [Versponse::OpenAPI::Declarations] the document's declarations
+      # @param version [String] version to build
+      def initialize(declarations, version)
+        @declarations = declarations
+        @version = version
+      end
+
+      # @return [Hash] the document, a copy the caller can change
+      # @raise [ArgumentError] for a version the document doesn't declare
+      # @raise [Versponse::DefinitionError] for colliding component names, an openapi version config.json_schema_version
+      #   doesn't write, or webhooks in an OpenAPI 3.0 document
+      def call
+        check_version!
+        # Components are the classes' frozen, cached schemas, so the caller and the hooks get a copy
+        document = DeepCopy.call(base.merge("components" => components))
+        # A hook that takes one argument gets only the document
+        @declarations.finalizers.each { |hook| (hook.arity == 1) ? hook.call(document) : hook.call(document, @version) }
+        document
+      end
+
+      private
+
+      def check_version!
+        versions = @declarations.versions
+        return if versions.empty? || versions.include?(@version)
+
+        raise ArgumentError, "#{@version} is not a version of this document (#{versions.join(", ")})"
+      end
+
+      def base
+        openapi = openapi_version
+        webhooks = resolve(@declarations.webhooks)
+        if webhooks && openapi.start_with?("3.0.")
+          raise DefinitionError, "webhooks need OpenAPI 3.1 (config.json_schema_version is :#{Versponse.configuration.json_schema_version})"
+        end
+
+        {
+          "openapi" => openapi,
+          "info" => info,
+          "externalDocs" => resolve(@declarations.external_docs),
+          "servers" => presence(resolve(@declarations.servers)),
+          "tags" => presence(resolve(@declarations.tags)),
+          "security" => resolve(@declarations.security),
+          "paths" => {},
+          "webhooks" => webhooks
+        }.compact
+      end
+
+      # Each layer is resolved for the version and merged over the ones before it
+      def info
+        @declarations.info.reduce({"version" => @version}) { |merged, layer| merged.merge(resolve(layer) || {}) }
+      end
+
+      def components
+        schemes = @declarations.security_schemes.transform_values { |scheme| resolve(scheme) }
+        {"securitySchemes" => presence(schemes), "schemas" => schemas}.compact
+      end
+
+      def schemas
+        set = ComponentSet.new
+        add_responses(set)
+        add_requests(set)
+        add_wrappers(set)
+        add_schemas(set)
+        set.to_h
+      end
+
+      def add_responses(set)
+        response_classes.each do |klass|
+          Versponse.components(version: @version, classes: [klass]).each { |name, schema| set.add(name, schema, klass.name) }
+        end
+      end
+
+      def add_requests(set)
+        request_classes.each do |klass|
+          References.check_dialect!(klass)
+          schema = request_schema(klass)
+          set.add(klass.component_name, schema, klass.name) if schema
+        end
+      end
+
+      # Wrapper schemas only $ref the class, so skip classes that don't cover the version (supported_versions)
+      def add_wrappers(set)
+        @declarations.wrappers.each_value do |wrapper|
+          next unless Components.resolved(wrapper.klass, @version)
+
+          schema = wrapper.klass.to_schema(version: @version, view: wrapper.view, root: wrapper.root, meta: wrapper.meta, collection: wrapper.collection)
+          set.add(wrapper.name, schema, "wrapper #{wrapper.name}")
+        end
+      end
+
+      # Hand-written components are schemas, so they're camelized like every other schema; other document values aren't
+      def add_schemas(set)
+        @declarations.schemas.each do |name, value|
+          value = resolve(value)
+          set.add(name, value.is_a?(Hash) ? Naming.camelize_keys(value) : value, "schema #{name}")
+        end
+      end
+
+      def response_classes
+        select(@declarations.response_sources, :responses, "response classes") { Registry.classes }
+      end
+
+      def request_classes
+        select(@declarations.request_sources, :requests, "body requests") { verquest_classes.select { |klass| Sources.body?(klass) } }
+      end
+
+      def select(sources, keyword, kind, &candidates)
+        sources.flat_map { |source| source.classes || Sources.in_namespace(keyword, source.namespace, kind, &candidates) }.uniq
+      end
+
+      def verquest_classes
+        raise DefinitionError, "requests namespace: needs verquest to be loaded" unless defined?(::Verquest::Base)
+
+        descendants(::Verquest::Base)
+      end
+
+      def descendants(klass)
+        klass.subclasses.flat_map { |subclass| [subclass, *descendants(subclass)] }
+      end
+
+      def request_schema(klass)
+        klass.to_schema(version: @version)
+      rescue *version_errors
+        nil
+      end
+
+      def version_errors
+        [VersionNotFoundError, (::Verquest::VersionNotFoundError if defined?(::Verquest::VersionNotFoundError))].compact
+      end
+
+      def presence(collection)
+        collection unless collection.empty?
+      end
+
+      # Schemas are written for config.json_schema_version, so the document declares the matching version
+      def openapi_version
+        openapi30 = Versponse.configuration.json_schema_version == :openapi30
+        declared = @declarations.openapi
+        return openapi30 ? "3.0.3" : "3.1.1" if declared.nil?
+        return declared if declared.start_with?("3.0.") == openapi30
+
+        raise DefinitionError, "openapi #{declared} doesn't match config.json_schema_version :#{Versponse.configuration.json_schema_version} (use #{openapi30 ? "3.0.x" : "3.1.x"})"
+      end
+
+      def resolve(value)
+        Values.resolve(value, @version)
+      end
+    end
+  end
+end

data/lib/versponse/open_api/component_set.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Versponse
+  module OpenAPI
+    # components.schemas of one build, remembering where each name came from
+    #
+    # @api private
+    class ComponentSet
+      # @return [ComponentSet] an empty set
+      def initialize
+        @schemas = {}
+        @sources = {}
+      end
+
+      # @param name [String] component name
+      # @param schema [Hash] component schema
+      # @param source [String] where it came from, for the collision message
+      # @return [void]
+      # @raise [Versponse::DefinitionError] when the name is already taken
+      def add(name, schema, source)
+        raise DefinitionError, "Component #{name} from #{source} collides with #{@sources[name]}" if @schemas.key?(name)
+
+        @schemas[name] = schema
+        @sources[name] = source
+      end
+
+      # @return [Hash{String => Hash}] the schemas
+      def to_h
+        @schemas
+      end
+    end
+  end
+end

data/lib/versponse/open_api/declarations.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Versponse
+  module OpenAPI
+    # Everything a document class declares. Subclasses get a copy, so they inherit and extend it.
+    #
+    # @api private
+    class Declarations
+      # One response or request source: an explicit list, or a namespace (Module or String) resolved at build
+      Source = Data.define(:classes, :namespace)
+      # One named wrapper component
+      Wrapper = Data.define(:name, :klass, :root, :collection, :meta, :view)
+
+      # @return [String, nil] rswag key prefix
+      attr_accessor :document_name
+      # @return [String, nil] openapi field, nil for the version config.json_schema_version writes
+      attr_accessor :openapi
+      # @return [Hash, Proc, nil] externalDocs
+      attr_accessor :external_docs
+      # @return [Array, Proc, nil] top-level security
+      attr_accessor :security
+      # @return [Hash, Proc, nil] top-level webhooks
+      attr_accessor :webhooks
+      # @return [Array<String>] versions exposed to rswag (empty = any version)
+      attr_accessor :versions
+      # @return [Array<Hash, Proc>] info layers, a subclass's after its parent's, merged in order at build
+      attr_reader :info
+      # @return [Array<Hash>] servers
+      attr_reader :servers
+      # @return [Array<Hash>] tags
+      attr_reader :tags
+      # @return [Hash{String => Hash, Proc}] securitySchemes by name
+      attr_reader :security_schemes
+      # @return [Array<Source>] response sources
+      attr_reader :response_sources
+      # @return [Array<Source>] request sources
+      attr_reader :request_sources
+      # @return [Hash{String => Wrapper}] wrapper components by name
+      attr_reader :wrappers
+      # @return [Hash{String => Hash, Proc}] hand-written components by name
+      attr_reader :schemas
+      # @return [Array<Proc>] finalize hooks
+      attr_reader :finalizers
+
+      # @return [Declarations] empty declarations
+      def initialize
+        @openapi = nil
+        @versions = []
+        @info = []
+        @servers = []
+        @tags = []
+        @security_schemes = {}
+        @response_sources = []
+        @request_sources = []
+        @wrappers = {}
+        @schemas = {}
+        @finalizers = []
+        @claimed = Set.new
+      end
+
+      # @param other [Declarations] declarations being copied
+      # @return [void]
+      def initialize_copy(other)
+        super
+        @versions = other.versions.dup
+        @info = other.info.dup
+        @servers = other.servers.dup
+        @tags = other.tags.dup
+        @security_schemes = other.security_schemes.dup
+        @response_sources = other.response_sources.dup
+        @request_sources = other.request_sources.dup
+        @wrappers = other.wrappers.dup
+        @schemas = other.schemas.dup
+        @finalizers = other.finalizers.dup
+        # A subclass may reuse its parent's names, which replaces the parent's entries in place
+        @claimed = Set.new
+      end
+
+      # Records a name this class declares
+      #
+      # @param keyword [Symbol] declaring method (:schema, :wrapper or :security_scheme)
+      # @param name [String] declared name
+      # @return [void]
+      # @raise [Versponse::DefinitionError] when this class already declared the name
+      def claim!(keyword, name)
+        raise DefinitionError, "#{keyword} #{name} is declared twice" unless @claimed.add?([keyword, name])
+      end
+    end
+  end
+end

data/lib/versponse/open_api/document.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Versponse
+  module OpenAPI
+    # Parent of OpenAPI document classes. Declare the base, components and hooks in the class body,
+    # then build one version with {.build}.
+    #
+    # @example
+    #   class PublicApiDocument < Versponse::OpenAPI::Document
+    #     document_name "public_api"
+    #     versions "2025-09", "preview"
+    #     info "title" => "Public API"
+    #     responses namespace: PublicApi
+    #   end
+    #
+    #   PublicApiDocument.build(version: "2025-09")
+    class Document
+      @declarations = Declarations.new
+
+      class << self
+        # @return [Versponse::OpenAPI::Declarations] this class's declarations
+        # @api private
+        attr_reader :declarations
+
+        # Gives the subclass a copy of the declarations so far
+        #
+        # @param subclass [Class] new document class
+        # @return [void]
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@declarations, declarations.dup)
+        end
+
+        # @param version [String] version to build
+        # @return [Hash] String-keyed OpenAPI document
+        # @raise [ArgumentError] for a version the document doesn't declare
+        # @raise [Versponse::DefinitionError] for colliding component names
+        def build(version:)
+          Builder.new(declarations, version.to_s).call
+        end
+
+        # Validates against the OpenAPI meta-schema, and checks that every local "$ref" ("#/...") resolves,
+        # which the meta-schema can't (a referenced class left out of responses, say)
+        #
+        # @param version [String] version to build and validate
+        # @return [Array<Hash>] errors with :pointer, :type, :message and :details (empty when valid)
+        def validate(version:)
+          require "json_schemer"
+
+          document = build(version:)
+          errors = JSONSchemer.openapi(document).validate.map do |error|
+            {pointer: error["data_pointer"], type: error["type"], message: error["error"], details: error["details"]}
+          end
+          errors + RefCheck.call(document)
+        end
+
+        # @param value [String, Symbol, nil] the prefix to declare, nil to read it
+        # @return [String, nil] the rswag key prefix
+        def document_name(value = nil)
+          return declarations.document_name if value.nil?
+
+          declarations.document_name = value.to_s
+        end
+
+        # @param names [Array<String, Symbol>] versions to declare, none to read them
+        # @return [Array<String>] declared versions
+        def versions(*names)
+          return declarations.versions.dup if names.empty?
+
+          declarations.versions = names.map(&:to_s)
+        end
+
+        # Alias of {versions} without arguments, kept for callers that read it under this name
+        #
+        # @return [Array<String>] declared versions
+        def document_versions = versions
+
+        # Component name of a declared wrapper or hand-written schema, inherited declarations included
+        #
+        # @param name [Symbol, String] a Symbol is turned into PascalCase as {wrapper} does (:contact_list is
+        #   "ContactList"), a String is used as given
+        # @return [String] component name
+        # @raise [Versponse::DefinitionError] when the document declares no such wrapper or schema
+        def component_name(name)
+          component = declared_name(name)
+          return component if declarations.wrappers.key?(component) || declarations.schemas.key?(component)
+
+          shown = name.is_a?(Symbol) ? "#{name.inspect} (#{component})" : name.inspect
+          raise DefinitionError, "#{self} declares no wrapper or schema #{shown}"
+        end
+
+        # @param name [Symbol, String] wrapper or schema name, as {component_name} takes it
+        # @return [String] "#/components/schemas/<name>" reference
+        # @raise [Versponse::DefinitionError] when the document declares no such wrapper or schema
+        def ref(name)
+          "#/components/schemas/#{component_name(name)}"
+        end
+
+        private
+
+        def declared_name(name)
+          name.is_a?(Symbol) ? Naming.pascalize(name) : name.to_s
+        end
+
+        def openapi(value)
+          declarations.openapi = value.to_s
+        end
+
+        def info(value = nil, &block)
+          declarations.info << required_value(:info, value, block)
+        end
+
+        def external_docs(value = nil, &block)
+          declarations.external_docs = required_value(:external_docs, value, block)
+        end
+
+        def security(value = nil, &block)
+          declarations.security = required_value(:security, value, block)
+        end
+
+        def server(url, description: nil, **extra)
+          declarations.servers << {"url" => url, "description" => description}.compact.merge(extensions(extra))
+        end
+
+        def tag(name, description: nil, **extra)
+          declarations.tags << {"name" => name, "description" => description}.compact.merge(extensions(extra))
+        end
+
+        def security_scheme(name, value = nil, &block)
+          value = required_value(:security_scheme, value, block)
+          declarations.claim!(:security_scheme, name.to_s)
+          declarations.security_schemes[name.to_s] = value
+        end
+
+        def responses(*classes, namespace: nil)
+          declarations.response_sources << source(:responses, classes.flatten, namespace)
+        end
+
+        def requests(*classes, namespace: nil)
+          declarations.request_sources << source(:requests, classes.flatten, namespace)
+        end
+
+        def wrapper(name, klass, root:, collection: false, meta: nil, view: :default)
+          Versponse::Wrapper.check_meta!(meta)
+          name = declared_name(name)
+          declarations.claim!(:wrapper, name)
+          declarations.wrappers[name] = Declarations::Wrapper.new(name:, klass:, root:, collection:, meta:, view:)
+        end
+
+        def schema(name, value = nil, &block)
+          value = required_value(:schema, value, block)
+          declarations.claim!(:schema, name.to_s)
+          declarations.schemas[name.to_s] = value
+        end
+
+        def webhooks(value = nil, &block)
+          declarations.webhooks = required_value(:webhooks, value, block)
+        end
+
+        def source(keyword, classes, namespace)
+          raise DefinitionError, "#{keyword} needs a list of classes or namespace:" if classes.empty? == namespace.nil?
+          return Declarations::Source.new(classes: nil, namespace: namespace.is_a?(Module) ? namespace : namespace.to_s) if namespace
+
+          Sources.check!(keyword, classes)
+          Declarations::Source.new(classes:, namespace: nil)
+        end
+
+        # Keyword keys that start with x_ are OpenAPI extensions: x_internal becomes "x-internal"
+        def extensions(extra)
+          extra.to_h { |key, value| [key.start_with?("x_") ? key.to_s.tr("_", "-") : key.to_s, value] }
+        end
+
+        def finalize(&block)
+          raise DefinitionError, "finalize needs a block" unless block
+
+          declarations.finalizers << block
+        end
+
+        def required_value(keyword, value, block)
+          raise DefinitionError, "#{keyword} needs a value or a block" if value.nil? && block.nil?
+
+          block || value
+        end
+      end
+    end
+  end
+end

data/lib/versponse/open_api/ref_check.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Versponse
+  module OpenAPI
+    # Finds local "$ref"s ("#/...") that point at nothing in a built document. Anchor references
+    # ("#Name"), external references and example values are left alone.
+    #
+    # @api private
+    module RefCheck
+      # Keywords whose values are data inside a Schema Object, so a "$ref" key in them isn't a reference ("examples"
+      # too when it's a schema's Array). Outside schemas only "example" is data: "default" is a response there.
+      DATA_KEYWORDS = %w[example default const enum].freeze
+
+      # Keywords whose keys are names (a property may be called "default"), not keywords
+      NAME_MAPS = %w[properties patternProperties $defs definitions dependentSchemas].freeze
+
+      # @param document [Hash] built OpenAPI document
+      # @return [Array<Hash>] errors with :pointer, :type, :message and :details
+      def self.call(document)
+        errors = []
+        walk(document, "", document, errors)
+        errors
+      end
+
+      # schema: true inside a Schema Object (below a "schema" key or a components/schemas entry)
+      def self.walk(value, pointer, document, errors, names: false, schema: false)
+        case value
+        when Hash then names ? walk_names(value, pointer, document, errors, schema:) : walk_object(value, pointer, document, errors, schema:)
+        when Array then value.each_with_index { |item, index| walk(item, "#{pointer}/#{index}", document, errors, schema:) }
+        end
+      end
+
+      def self.walk_names(map, pointer, document, errors, schema:)
+        map.each { |name, item| walk(item, "#{pointer}/#{escape(name)}", document, errors, schema:) }
+      end
+
+      def self.walk_object(object, pointer, document, errors, schema:)
+        check(object["$ref"], pointer, document, errors) if object["$ref"].is_a?(String)
+        check_mapping(object["discriminator"], "#{pointer}/discriminator", document, errors)
+        object.each do |key, item|
+          next if data?(key, item, schema:)
+
+          components = key == "schemas" && pointer == "/components"
+          walk(item, "#{pointer}/#{escape(key)}", document, errors,
+            names: components || (schema && NAME_MAPS.include?(key)), schema: schema || components || key == "schema")
+        end
+      end
+
+      def self.data?(key, item, schema:)
+        return key == "example" unless schema
+
+        DATA_KEYWORDS.include?(key) || (key == "examples" && !item.is_a?(Hash))
+      end
+
+      def self.check_mapping(discriminator, pointer, document, errors)
+        return unless discriminator.is_a?(Hash) && discriminator["mapping"].is_a?(Hash)
+
+        discriminator["mapping"].each do |value, ref|
+          check(ref, "#{pointer}/mapping/#{escape(value)}", document, errors) if ref.is_a?(String)
+        end
+      end
+
+      def self.check(ref, pointer, document, errors)
+        return unless ref.start_with?("#/")
+        return if resolves?(document, ref)
+
+        errors << {pointer:, type: "ref", message: "$ref #{ref} does not resolve in the document", details: {"ref" => ref}}
+      end
+
+      def self.resolves?(document, ref)
+        ref.delete_prefix("#/").split("/").reduce(document) do |node, token|
+          token = token.gsub("~1", "/").gsub("~0", "~")
+          case node
+          when Hash then node.fetch(token) { return false }
+          when Array then (/\A\d+\z/.match?(token) && token.to_i < node.size) ? node[token.to_i] : (return false)
+          else return false
+          end
+        end
+        true
+      end
+
+      def self.escape(key)
+        key.to_s.gsub("~", "~0").gsub("/", "~1")
+      end
+
+      private_class_method :walk, :walk_names, :walk_object, :data?, :check_mapping, :check, :resolves?, :escape
+    end
+  end
+end

data/lib/versponse/open_api/rswag_specs.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Versponse
+  module OpenAPI
+    # rswag's config.openapi_specs: maps "name/version.json" keys to lazily built, memoized,
+    # symbol-keyed documents (rswag merges paths with symbol keys). Security scheme "type" and "in"
+    # values are symbols too: rswag compares them with :apiKey and :header to send API key headers.
+    class RswagSpecs
+      include Enumerable
+
+      # @param documents [Array<Class>] Versponse::OpenAPI::Document subclasses with document_name and versions
+      # @raise [Versponse::DefinitionError] when a document has no document_name
+      # @raise [Versponse::DefinitionError] when a document has no versions
+      def initialize(documents)
+        @entries = documents.each_with_object({}) do |document, entries|
+          raise DefinitionError, "#{document.name} needs document_name for rswag" unless document.document_name
+          raise DefinitionError, "#{document.name} needs versions for rswag" if document.document_versions.empty?
+
+          document.document_versions.each { |version| entries["#{document.document_name}/#{version}.json"] = [document, version] }
+        end
+        @built = {}
+      end
+
+      # @param key [String] e.g. "public_api/2025-09.json" (.yaml and .yml are accepted too)
+      # @return [Hash, nil] the symbol-keyed document, nil for an unknown key (rswag checks for nil); built on
+      #   first access and kept, because rswag merges its paths into it
+      def [](key)
+        key = normalize(key)
+        return unless @entries.key?(key)
+
+        @built[key] ||= symbolize_security_schemes(symbolize(build(key)))
+      end
+
+      # @param key [String] document key
+      # @return [Hash] the symbol-keyed document
+      # @raise [KeyError] for an unknown key
+      def fetch(key)
+        self[key] || raise(KeyError, "Unknown OpenAPI document #{key}")
+      end
+
+      # @yieldparam key [String] document key
+      # @yieldparam document [Hash] symbol-keyed document
+      # @return [Enumerator, void] an enumerator without a block
+      def each
+        return enum_for(:each) unless block_given?
+
+        keys.each { |key| yield key, self[key] }
+      end
+
+      # @return [Array<String>] every document key
+      def keys
+        @entries.keys
+      end
+
+      # @return [Array<Hash>] every document
+      def values
+        keys.map { |key| self[key] }
+      end
+
+      # @param key [String] document key
+      # @return [Boolean] whether the key is known
+      def key?(key)
+        @entries.key?(normalize(key))
+      end
+
+      # @return [Boolean] true when no document is declared
+      def empty?
+        @entries.empty?
+      end
+
+      private
+
+      def normalize(key)
+        key.to_s.sub(/\.ya?ml\z/, ".json")
+      end
+
+      def build(key)
+        document, version = @entries.fetch(key)
+        document.build(version:)
+      end
+
+      def symbolize_security_schemes(document)
+        document.dig(:components, :securitySchemes)&.each_value do |scheme|
+          scheme.slice(:type, :in).each { |name, value| scheme[name] = value.to_sym }
+        end
+        document
+      end
+
+      def symbolize(value)
+        case value
+        when Hash then value.to_h { |key, item| [key.to_sym, symbolize(item)] }
+        when Array then value.map { |item| symbolize(item) }
+        else value
+        end
+      end
+    end
+  end
+end