apiwork 0.0.0.pre → 0.1.1

data/lib/apiwork/introspection/action.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    # @api public
+    # Wraps action definitions within a resource.
+    #
+    # @example
+    #   resource.actions[:show].method # => :get
+    #   resource.actions[:show].path # => "/posts/:id"
+    #   resource.actions[:create].request # => Action::Request
+    #
+    #   resource.actions.each_value do |action|
+    #     action.method # => :get, :post, :patch, :delete
+    #     action.request # => Action::Request
+    #     action.response # => Action::Response
+    #     action.deprecated? # => false
+    #   end
+    class Action
+      def initialize(dump)
+        @dump = dump
+      end
+
+      # @api public
+      # The path for this action.
+      #
+      # @return [String]
+      def path
+        @dump[:path]
+      end
+
+      # @api public
+      # The method for this action.
+      #
+      # @return [Symbol]
+      def method
+        @dump[:method]
+      end
+
+      # @api public
+      # The request for this action.
+      #
+      # @return [Action::Request]
+      def request
+        @request ||= Request.new(@dump[:request])
+      end
+
+      # @api public
+      # The response for this action.
+      #
+      # @return [Action::Response]
+      def response
+        @response ||= Response.new(@dump[:response])
+      end
+
+      # @api public
+      # The raises for this action.
+      #
+      # @return [Array<Symbol>]
+      def raises
+        @dump[:raises]
+      end
+
+      # @api public
+      # The summary for this action.
+      #
+      # @return [String, nil]
+      def summary
+        @dump[:summary]
+      end
+
+      # @api public
+      # The description for this action.
+      #
+      # @return [String, nil]
+      def description
+        @dump[:description]
+      end
+
+      # @api public
+      # The tags for this action.
+      #
+      # @return [Array<String>]
+      def tags
+        @dump[:tags]
+      end
+
+      # @api public
+      # The operation ID for this action.
+      #
+      # @return [String, nil]
+      def operation_id
+        @dump[:operation_id]
+      end
+
+      # @api public
+      # Whether this action is deprecated.
+      #
+      # @return [Boolean]
+      def deprecated?
+        @dump[:deprecated]
+      end
+
+      # @api public
+      # Converts this action to a hash.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          deprecated: deprecated?,
+          description: description,
+          method: method,
+          operation_id: operation_id,
+          path: path,
+          raises: raises,
+          request: request.to_h,
+          response: response.to_h,
+          summary: summary,
+          tags: tags,
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    class API
+      class Info
+        # @api public
+        # Wraps API contact information.
+        #
+        # @example
+        #   contact = api.info.contact
+        #   contact.name # => "API Support"
+        #   contact.email # => "support@example.com"
+        #   contact.url # => "https://example.com/support"
+        class Contact
+          def initialize(dump)
+            @dump = dump
+          end
+
+          # @api public
+          # The contact name.
+          #
+          # @return [String, nil]
+          def name
+            @dump[:name]
+          end
+
+          # @api public
+          # The contact email.
+          #
+          # @return [String, nil]
+          def email
+            @dump[:email]
+          end
+
+          # @api public
+          # The contact URL.
+          #
+          # @return [String, nil]
+          def url
+            @dump[:url]
+          end
+
+          # @api public
+          # Converts this contact to a hash.
+          #
+          # @return [Hash]
+          def to_h
+            {
+              email: email,
+              name: name,
+              url: url,
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    class API
+      class Info
+        # @api public
+        # Wraps API license information.
+        #
+        # @example
+        #   license = api.info.license
+        #   license.name # => "MIT"
+        #   license.url # => "https://opensource.org/licenses/MIT"
+        class License
+          def initialize(dump)
+            @dump = dump
+          end
+
+          # @api public
+          # The license name.
+          #
+          # @return [String, nil]
+          def name
+            @dump[:name]
+          end
+
+          # @api public
+          # The license URL.
+          #
+          # @return [String, nil]
+          def url
+            @dump[:url]
+          end
+
+          # @api public
+          # Converts this license to a hash.
+          #
+          # @return [Hash]
+          def to_h
+            {
+              name: name,
+              url: url,
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    class API
+      class Info
+        # @api public
+        # Wraps API server information.
+        #
+        # @example
+        #   api.info.servers.each do |server|
+        #     puts server.url # => "https://api.example.com"
+        #     puts server.description # => "Production server"
+        #   end
+        class Server
+          def initialize(dump)
+            @dump = dump
+          end
+
+          # @api public
+          # The server URL.
+          #
+          # @return [String, nil]
+          def url
+            @dump[:url]
+          end
+
+          # @api public
+          # The server description.
+          #
+          # @return [String, nil]
+          def description
+            @dump[:description]
+          end
+
+          # @api public
+          # Converts this server to a hash.
+          #
+          # @return [Hash]
+          def to_h
+            {
+              description: description,
+              url: url,
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    class API
+      # @api public
+      # Wraps API metadata/info.
+      #
+      # @example
+      #   info = api.info
+      #   info.title # => "My API"
+      #   info.version # => "1.0.0"
+      #   info.description # => "API for managing resources"
+      #   info.contact&.email # => "support@example.com"
+      #   info.license&.name # => "MIT"
+      class Info
+        def initialize(dump)
+          @dump = dump
+        end
+
+        # @api public
+        # The API title.
+        #
+        # @return [String, nil]
+        def title
+          @dump[:title]
+        end
+
+        # @api public
+        # The API version.
+        #
+        # @return [String, nil]
+        def version
+          @dump[:version]
+        end
+
+        # @api public
+        # The API description.
+        #
+        # @return [String, nil]
+        def description
+          @dump[:description]
+        end
+
+        # @api public
+        # The API summary.
+        #
+        # @return [String, nil]
+        def summary
+          @dump[:summary]
+        end
+
+        # @api public
+        # The API terms of service.
+        #
+        # @return [String, nil]
+        def terms_of_service
+          @dump[:terms_of_service]
+        end
+
+        # @api public
+        # The API contact.
+        #
+        # @return [Info::Contact, nil]
+        # @see Info::Contact
+        def contact
+          @contact ||= @dump[:contact] ? Contact.new(@dump[:contact]) : nil
+        end
+
+        # @api public
+        # The API license.
+        #
+        # @return [Info::License, nil]
+        # @see Info::License
+        def license
+          @license ||= @dump[:license] ? License.new(@dump[:license]) : nil
+        end
+
+        # @api public
+        # The API servers.
+        #
+        # @return [Array<Info::Server>]
+        # @see Info::Server
+        def servers
+          @servers ||= @dump[:servers].map { |server| Server.new(server) }
+        end
+
+        # @api public
+        # Converts the API info to a hash.
+        #
+        # @return [Hash]
+        def to_h
+          {
+            contact: contact&.to_h,
+            description: description,
+            license: license&.to_h,
+            servers: servers.map(&:to_h),
+            summary: summary,
+            terms_of_service: terms_of_service,
+            title: title,
+            version: version,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/introspection/api/resource.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    class API
+      # @api public
+      # Wraps resource definitions.
+      #
+      # @example
+      #   resource = api.resources[:invoices]
+      #
+      #   resource.identifier # => "invoices"
+      #   resource.path # => "invoices"
+      #   resource.parent_identifiers # => []
+      #   resource.resources # => {} or nested resources
+      #
+      #   resource.actions.each_value do |action|
+      #     action.request # => Action::Request
+      #     action.response # => Action::Response
+      #   end
+      class Resource
+        def initialize(dump)
+          @dump = dump
+        end
+
+        # @api public
+        # The identifier for this resource.
+        #
+        # @return [String]
+        def identifier
+          @dump[:identifier]
+        end
+
+        # @api public
+        # The path for this resource.
+        #
+        # @return [String]
+        def path
+          @dump[:path]
+        end
+
+        # @api public
+        # The parent identifiers for this resource.
+        #
+        # @return [Array<String>]
+        def parent_identifiers
+          @dump[:parent_identifiers]
+        end
+
+        # @api public
+        # The actions for this resource.
+        #
+        # @return [Hash{Symbol => Introspection::Action}]
+        # @see Introspection::Action
+        def actions
+          @actions ||= @dump[:actions].transform_values { |dump| Action.new(dump) }
+        end
+
+        # @api public
+        # The nested resources for this resource.
+        #
+        # @return [Hash{Symbol => Resource}]
+        def resources
+          @resources ||= @dump[:resources].transform_values { |dump| Resource.new(dump) }
+        end
+
+        # @api public
+        # Converts this resource to a hash.
+        #
+        # @return [Hash]
+        def to_h
+          {
+            actions: actions.transform_values(&:to_h),
+            identifier: identifier,
+            parent_identifiers: parent_identifiers,
+            path: path,
+            resources: resources.transform_values(&:to_h),
+          }
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/introspection/api.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    # @api public
+    # Facade for introspected API data.
+    #
+    # Entry point for accessing all API data. Access resources via {#resources},
+    # types via {#types}, enums via {#enums}.
+    #
+    # @example
+    #   api = Apiwork::API.introspect('/api/v1', locale: :fr)
+    #
+    #   api.info.title # => "Mon API"
+    #   api.types[:address].description # => "Type d'adresse"
+    #   api.enums[:status].values # => ["draft", "published"]
+    #
+    #   api.resources.each_value do |resource|
+    #     resource.actions.each_value do |action|
+    #       # ...
+    #     end
+    #   end
+    class API
+      def initialize(dump)
+        @dump = dump
+      end
+
+      # @api public
+      # The base path for this API.
+      #
+      # @return [String, nil]
+      def base_path
+        @dump[:base_path]
+      end
+
+      # @api public
+      # The info for this API.
+      #
+      # @return [API::Info, nil]
+      def info
+        @info ||= @dump[:info] ? Info.new(@dump[:info]) : nil
+      end
+
+      # @api public
+      # The resources for this API.
+      #
+      # @return [Hash{Symbol => API::Resource}]
+      def resources
+        @resources ||= @dump[:resources].transform_values { |dump| Resource.new(dump) }
+      end
+
+      # @api public
+      # The types for this API.
+      #
+      # @return [Hash{Symbol => Type}]
+      def types
+        @types ||= @dump[:types].transform_values { |dump| Type.new(dump) }
+      end
+
+      # @api public
+      # The enums for this API.
+      #
+      # @return [Hash{Symbol => Enum}]
+      def enums
+        @enums ||= @dump[:enums].transform_values { |dump| Enum.new(dump) }
+      end
+
+      # @api public
+      # The error codes for this API.
+      #
+      # @return [Hash{Symbol => ErrorCode}]
+      def error_codes
+        @error_codes ||= @dump[:error_codes].transform_values { |dump| ErrorCode.new(dump) }
+      end
+
+      # @api public
+      # Converts this API to a hash.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          base_path:,
+          enums: enums.transform_values(&:to_h),
+          error_codes: error_codes.transform_values(&:to_h),
+          info: info&.to_h,
+          resources: resources.transform_values(&:to_h),
+          types: types.transform_values(&:to_h),
+        }
+      end
+    end
+  end
+end

data/lib/apiwork/introspection/contract.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    # @api public
+    # Facade for introspected contract data.
+    #
+    # Provides access to actions, types, and enums defined on this contract.
+    #
+    # @example
+    #   contract = InvoiceContract.introspect(expand: true)
+    #
+    #   contract.actions[:show].response # => Action::Response
+    #   contract.types[:address].shape # => { street: ..., city: ... }
+    #   contract.enums[:status].values # => ["draft", "published"]
+    #
+    #   contract.actions.each_value do |action|
+    #     action.request # => Action::Request
+    #     action.response # => Action::Response
+    #   end
+    class Contract
+      def initialize(dump)
+        @dump = dump
+      end
+
+      # @api public
+      # The actions for this contract.
+      #
+      # @return [Hash{Symbol => Introspection::Action}]
+      def actions
+        @actions ||= @dump[:actions].transform_values { |dump| Action.new(dump) }
+      end
+
+      # @api public
+      # The types for this contract.
+      #
+      # @return [Hash{Symbol => Type}]
+      def types
+        @types ||= @dump[:types].transform_values { |dump| Type.new(dump) }
+      end
+
+      # @api public
+      # The enums for this contract.
+      #
+      # @return [Hash{Symbol => Enum}]
+      def enums
+        @enums ||= @dump[:enums].transform_values { |dump| Enum.new(dump) }
+      end
+
+      # @api public
+      # Converts this contract to a hash.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          actions: actions.transform_values(&:to_h),
+          enums: enums.transform_values(&:to_h),
+          types: types.transform_values(&:to_h),
+        }
+      end
+    end
+  end
+end