apiwork 0.0.0.pre → 0.1.1

data/lib/apiwork/api/element.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module API
+    # @api public
+    # Block context for defining a single type expression.
+    #
+    # Used inside `array do` and `variant do` blocks where
+    # exactly one element type must be defined.
+    #
+    # @see API::Object Block context for object params
+    # @see API::Union Block context for union variants
+    #
+    # @example instance_eval style
+    #   array :ids do
+    #     integer
+    #   end
+    #
+    # @example yield style
+    #   array :ids do |element|
+    #     element.integer
+    #   end
+    #
+    # @example Array of references
+    #   array :items do |element|
+    #     element.reference :item
+    #   end
+    class Element < Apiwork::Element
+      # @api public
+      # Defines the element type.
+      #
+      # This is the verbose form. Prefer sugar methods (string, integer, etc.)
+      # for static definitions. Use `of` for dynamic element generation.
+      #
+      # @param type [Symbol] [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :literal, :number, :object, :string, :time, :union, :uuid]
+      #   The element type. Custom type references are also allowed.
+      # @param discriminator [Symbol, nil] (nil)
+      #   The discriminator field name. Unions only.
+      # @param enum [Array, Symbol, nil] (nil)
+      #   The allowed values. Strings and integers only.
+      # @param format [Symbol, nil] (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :url, :uuid]
+      #   Format hint for exports. Does not change the type, but exports may add validation or documentation based on it.
+      #   Valid formats by type: `:decimal`/`:number` (`:double`, `:float`), `:integer` (`:int32`, `:int64`),
+      #   `:string` (`:date`, `:datetime`, `:email`, `:hostname`, `:ipv4`, `:ipv6`, `:password`, `:url`, `:uuid`).
+      # @param max [Integer, nil] (nil)
+      #   The maximum. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
+      # @param min [Integer, nil] (nil)
+      #   The minimum. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
+      # @param value [Object, nil] (nil)
+      #   The literal value. Literals only.
+      # @yield block for defining nested structure
+      # @yieldparam shape [API::Object, API::Union, API::Element]
+      # @return [void]
+      #
+      # @example Dynamic element type
+      #   element_type = :string
+      #   array :values do
+      #     of element_type
+      #   end
+      #
+      # @example Object with block
+      #   array :tags do
+      #     of :object do
+      #       string :name
+      #     end
+      #   end
+      def of(type, discriminator: nil, enum: nil, format: nil, max: nil, min: nil, value: nil, &block)
+        case type
+        when :string, :integer, :decimal, :boolean, :number, :datetime, :date, :uuid, :time, :binary
+          set_type(type, enum:, format:, max:, min:)
+        when :literal
+          @type = :literal
+          @value = value
+          @defined = true
+        when :object
+          @type = :object
+          if block
+            shape = Object.new
+            block.arity.positive? ? yield(shape) : shape.instance_eval(&block)
+            @shape = shape
+          end
+          @defined = true
+        when :array
+          raise ConfigurationError, 'array requires a block' unless block
+
+          inner = Element.new
+          block.arity.positive? ? yield(inner) : inner.instance_eval(&block)
+          inner.validate!
+          @type = :array
+          @inner = inner
+          @shape = inner.shape
+          @defined = true
+        when :union
+          raise ConfigurationError, 'union requires a block' unless block
+
+          shape = Union.new(discriminator:)
+          block.arity.positive? ? yield(shape) : shape.instance_eval(&block)
+          @type = :union
+          @shape = shape
+          @discriminator = discriminator
+          @defined = true
+        else
+          @type = type
+          @custom_type = type
+          @defined = true
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/api/enum_registry/definition.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module API
+    class EnumRegistry
+      class Definition
+        attr_reader :description,
+                    :example,
+                    :name,
+                    :scope,
+                    :values
+
+        def initialize(
+          name,
+          scope: nil,
+          deprecated: false,
+          description: nil,
+          example: nil,
+          values: nil
+        )
+          @name = name
+          @scope = scope
+          @deprecated = deprecated
+          @description = description
+          @example = example
+          @values = values
+        end
+
+        def deprecated?
+          @deprecated == true
+        end
+
+        def merge(
+          deprecated:,
+          description:,
+          example:,
+          values:
+        )
+          Definition.new(
+            @name,
+            deprecated: deprecated || @deprecated,
+            description: description || @description,
+            example: example || @example,
+            scope: @scope,
+            values: values || @values,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/api/enum_registry.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module API
+    class EnumRegistry
+      def initialize
+        @store = {}
+      end
+
+      def register(
+        name,
+        values = nil,
+        scope: nil,
+        deprecated: false,
+        description: nil,
+        example: nil
+      )
+        key = scoped_name(scope, name)
+
+        if @store.key?(key)
+          merge(
+            key,
+            deprecated:,
+            description:,
+            example:,
+            values:,
+          )
+        else
+          @store[key] = Definition.new(
+            key,
+            deprecated:,
+            description:,
+            example:,
+            scope:,
+            values:,
+          )
+        end
+      end
+
+      def [](name)
+        @store[name]
+      end
+
+      def key?(name)
+        @store.key?(name)
+      end
+
+      def each_pair(&block)
+        @store.each_pair(&block)
+      end
+
+      def exists?(name, scope: nil)
+        find(name, scope:).present?
+      end
+
+      def find(name, scope: nil)
+        (scope ? @store[scoped_name(scope, name)] : nil) || @store[name]
+      end
+
+      def values(name, scope: nil)
+        find(name, scope:)&.values
+      end
+
+      def scoped_name(scope, name)
+        return name unless scope
+
+        prefix = scope.respond_to?(:scope_prefix) ? scope.scope_prefix : nil
+        return name unless prefix
+        return prefix.to_sym if name.nil?
+        return prefix.to_sym if name.to_s.empty?
+        return name.to_sym if name.to_s == prefix
+
+        [prefix, name].join('_').to_sym
+      end
+
+      def clear!
+        @store.clear
+      end
+
+      private
+
+      def merge(
+        key,
+        deprecated:,
+        description:,
+        example:,
+        values:
+      )
+        @store[key] = @store[key].merge(
+          deprecated:,
+          description:,
+          example:,
+          values:,
+        )
+      end
+    end
+  end
+end

data/lib/apiwork/api/info/contact.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module API
+    class Info
+      # @api public
+      # Contact information block.
+      #
+      # Used within the `contact` block in {API::Info}.
+      class Contact
+        def initialize
+          @email = nil
+          @name = nil
+          @url = nil
+        end
+
+        # @api public
+        # The contact name.
+        #
+        # @param value [String, nil] (nil)
+        #   The name.
+        # @return [String, nil]
+        #
+        # @example
+        #   name 'API Support'
+        #   contact.name # => "API Support"
+        def name(value = nil)
+          return @name if value.nil?
+
+          @name = value
+        end
+
+        # @api public
+        # The contact email.
+        #
+        # @param value [String, nil] (nil)
+        #   The email.
+        # @return [String, nil]
+        #
+        # @example
+        #   email 'support@example.com'
+        #   contact.email # => "support@example.com"
+        def email(value = nil)
+          return @email if value.nil?
+
+          @email = value
+        end
+
+        # @api public
+        # The contact URL.
+        #
+        # @param value [String, nil] (nil)
+        #   The URL.
+        # @return [String, nil]
+        #
+        # @example
+        #   url 'https://example.com/support'
+        #   contact.url # => "https://example.com/support"
+        def url(value = nil)
+          return @url if value.nil?
+
+          @url = value
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/api/info/license.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module API
+    class Info
+      # @api public
+      # License information block.
+      #
+      # Used within the `license` block in {API::Info}.
+      class License
+        def initialize
+          @name = nil
+          @url = nil
+        end
+
+        # @api public
+        # The license name.
+        #
+        # @param value [String, nil] (nil)
+        #   The name.
+        # @return [String, nil]
+        #
+        # @example
+        #   name 'MIT'
+        #   license.name # => "MIT"
+        def name(value = nil)
+          return @name if value.nil?
+
+          @name = value
+        end
+
+        # @api public
+        # The license URL.
+        #
+        # @param value [String, nil] (nil)
+        #   The URL.
+        # @return [String, nil]
+        #
+        # @example
+        #   url 'https://opensource.org/licenses/MIT'
+        #   license.url # => "https://opensource.org/licenses/MIT"
+        def url(value = nil)
+          return @url if value.nil?
+
+          @url = value
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/api/info/server.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module API
+    class Info
+      # @api public
+      # Server definition block.
+      #
+      # Used within the `server` block in {API::Info}.
+      class Server
+        def initialize
+          @description = nil
+          @url = nil
+        end
+
+        # @api public
+        # The server URL.
+        #
+        # @param value [String, nil] (nil)
+        #   The URL.
+        # @return [String, nil]
+        #
+        # @example
+        #   url 'https://api.example.com'
+        #   server.url # => "https://api.example.com"
+        def url(value = nil)
+          return @url if value.nil?
+
+          @url = value
+        end
+
+        # @api public
+        # The server description.
+        #
+        # @param value [String, nil] (nil)
+        #   The description.
+        # @return [String, nil]
+        #
+        # @example
+        #   description 'Production'
+        #   server.description # => "Production"
+        def description(value = nil)
+          return @description if value.nil?
+
+          @description = value
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/api/info.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module API
+    # @api public
+    # Block context for defining API metadata.
+    #
+    # Used within the `info` block in {API::Base}.
+    class Info
+      def initialize
+        @contact = nil
+        @deprecated = false
+        @description = nil
+        @license = nil
+        @servers = []
+        @summary = nil
+        @tags = []
+        @terms_of_service = nil
+        @title = nil
+        @version = nil
+      end
+
+      # @api public
+      # The API title.
+      #
+      # @param value [String, nil] (nil)
+      #   The title.
+      # @return [String, nil]
+      #
+      # @example
+      #   title 'Invoice API'
+      #   info.title # => "Invoice API"
+      def title(value = nil)
+        return @title if value.nil?
+
+        @title = value
+      end
+
+      # @api public
+      # The API version.
+      #
+      # @param value [String, nil] (nil)
+      #   The version.
+      # @return [String, nil]
+      #
+      # @example
+      #   version '1.0.0'
+      #   info.version # => "1.0.0"
+      def version(value = nil)
+        return @version if value.nil?
+
+        @version = value
+      end
+
+      # @api public
+      # The API terms of service.
+      #
+      # @param value [String, nil] (nil)
+      #   The URL to terms of service.
+      # @return [String, nil]
+      #
+      # @example
+      #   terms_of_service 'https://example.com/terms'
+      #   info.terms_of_service # => "https://example.com/terms"
+      def terms_of_service(value = nil)
+        return @terms_of_service if value.nil?
+
+        @terms_of_service = value
+      end
+
+      # @api public
+      # The API contact.
+      #
+      # @yield block for defining contact info
+      # @yieldparam contact [Contact]
+      # @return [Contact, nil]
+      #
+      # @example instance_eval style
+      #   contact do
+      #     name 'Support'
+      #     email 'support@example.com'
+      #   end
+      #
+      # @example yield style
+      #   contact do |contact|
+      #     contact.name 'Support'
+      #     contact.email 'support@example.com'
+      #   end
+      def contact(&block)
+        return @contact unless block
+
+        @contact = Contact.new
+        block.arity.positive? ? yield(@contact) : @contact.instance_eval(&block)
+        @contact
+      end
+
+      # @api public
+      # The API license.
+      #
+      # @yield block for defining license info
+      # @yieldparam license [License]
+      # @return [License, nil]
+      #
+      # @example instance_eval style
+      #   license do
+      #     name 'MIT'
+      #     url 'https://opensource.org/licenses/MIT'
+      #   end
+      #
+      # @example yield style
+      #   license do |license|
+      #     license.name 'MIT'
+      #     license.url 'https://opensource.org/licenses/MIT'
+      #   end
+      def license(&block)
+        return @license unless block
+
+        @license = License.new
+        block.arity.positive? ? yield(@license) : @license.instance_eval(&block)
+        @license
+      end
+
+      # @api public
+      # Defines a server for the API.
+      #
+      # Can be called multiple times.
+      #
+      # @yield block for defining server info
+      # @yieldparam server [Server]
+      # @return [Array<Server>]
+      #
+      # @example instance_eval style
+      #   server do
+      #     url 'https://api.example.com'
+      #     description 'Production'
+      #   end
+      #
+      # @example yield style
+      #   server do |server|
+      #     server.url 'https://api.example.com'
+      #     server.description 'Production'
+      #   end
+      def server(&block)
+        return @servers unless block
+
+        server = Server.new
+        block.arity.positive? ? yield(server) : server.instance_eval(&block)
+        @servers << server
+      end
+
+      # @api public
+      # The API summary.
+      #
+      # @param value [String, nil] (nil)
+      #   The summary.
+      # @return [String, nil]
+      #
+      # @example
+      #   summary 'Invoice management API'
+      #   info.summary # => "Invoice management API"
+      def summary(value = nil)
+        return @summary if value.nil?
+
+        @summary = value
+      end
+
+      # @api public
+      # The API description.
+      #
+      # @param value [String, nil] (nil)
+      #   The description.
+      # @return [String, nil]
+      #
+      # @example
+      #   description 'Full-featured API for managing invoices and payments.'
+      #   info.description # => "Full-featured..."
+      def description(value = nil)
+        return @description if value.nil?
+
+        @description = value
+      end
+
+      # @api public
+      # The API tags.
+      #
+      # @param values [Array<String>]
+      #   The tags.
+      # @return [Array<String>]
+      #
+      # @example
+      #   tags 'invoices', 'payments'
+      #   info.tags # => ["invoices", "payments"]
+      def tags(*values)
+        return @tags if values.empty?
+
+        @tags = values.flatten
+      end
+
+      # @api public
+      # Marks the API as deprecated.
+      #
+      # @return [void]
+      #
+      # @example
+      #   info do
+      #     deprecated!
+      #   end
+      def deprecated!
+        @deprecated = true
+      end
+
+      # @api public
+      # Whether the API is deprecated.
+      #
+      # @return [Boolean]
+      def deprecated?
+        @deprecated
+      end
+    end
+  end
+end