apiwork 0.6.1 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7d4674d14687a7f9eb3547135c22df22c1cada2dc55b7f2b0f011462d20bf1a
-  data.tar.gz: f580dcdf234e49b933b1636f2a2c14d2ca11caf4d5364a70ec574763978c834c
+  metadata.gz: 5949ff5143ec3bdd3c0349b639eb17306ce00d32c6567a618bdd1f8f3474d9fc
+  data.tar.gz: 3d8e835b75f3c85725e17459ae24c6b6154002b7733f76315826a776799a9860
 SHA512:
-  metadata.gz: 33a16b4c739c5c13ba2374882d0997bea4cda29b00eef1c1afe7c810fe0247fab1ca6568bb225ac8e32617742b0ff9df85920518db7a4c062a223cdc688cee6b
-  data.tar.gz: d707cbf17e3df65f57a523e7695b5ce2c7d009b3aa28599b071fb0ec1ba910281af9224493708214654a979ffe6362d661d6d5410bcec93ffadc08e37c9f6f96
+  metadata.gz: 93ac9cbc50161930b09f247309256590241180080a710c2e49621874a654a0d70d02888a9972ed342058047312371b5de9f47f0039f4f09525991e2a3ba252a7
+  data.tar.gz: 757058cf4777c10627862c7dd4142473c76027f340042d636978a805c8adaa82e2c74963e366d168cb2140273e5e845bc3fba8bb9fe76d5d5f5a21d5ad9ce208

data/README.md

@@ -1,7 +1,12 @@
 # Apiwork
 
-![Apiwork](docs/public/logo-light.svg#gh-light-mode-only)
-![Apiwork](docs/public/logo-dark.svg#gh-dark-mode-only)
+![Apiwork](docs/public/banner.svg)
+
+---
+
+> 🚧 **Apiwork is pre-1.0 and working toward a stable 1.0.** Minor versions can still bring breaking changes, so follow the [changelog](./CHANGELOG.md).
+
+---
 
 [![Gem Version](https://img.shields.io/gem/v/apiwork)](https://rubygems.org/gems/apiwork)
 [![CI](https://github.com/skiftle/apiwork/actions/workflows/ci.yml/badge.svg)](https://github.com/skiftle/apiwork/actions/workflows/ci.yml)

data/lib/apiwork/adapter/serializer/error/default/api_builder.rb

@@ -12,7 +12,12 @@ module Apiwork
               object(:error_issue) do |object|
                 object.string(:code)
                 object.string(:detail)
-                object.array(:path, &:string)
+                object.array(:path) do |array|
+                  array.of(:union) do |union|
+                    union.variant(&:string)
+                    union.variant(&:integer)
+                  end
+                end
                 object.string(:pointer)
                 object.object(:meta)
               end

data/lib/apiwork/adapter/standard/capability/writing/contract_builder.rb

@@ -168,6 +168,7 @@ module Apiwork
                 type: attribute.type,
               }
 
+              options[:default] = attribute.default if attribute.default? && action_name == :create
               options[:min] = attribute.min if attribute.min
               options[:max] = attribute.max if attribute.max
               options[:of] = attribute.of if attribute.of

data/lib/apiwork/api/base.rb

@@ -763,6 +763,13 @@ module Apiwork
           result.transform { |hash| hash.deep_transform_keys { |key| transform_key(key).to_sym } }
         end
 
+        def prepare_error_response(response)
+          result = prepare_response(response)
+          return result if key_format == :keep
+
+          result.transform { |body| transform_issue_paths(body) }
+        end
+
         def type?(name, scope: nil)
           type_registry.exists?(name, scope:)
         end
@@ -838,6 +845,30 @@ module Apiwork
 
         private
 
+        def transform_issue_paths(body)
+          return body unless body.is_a?(Hash)
+          return body unless body[:issues].is_a?(Array)
+
+          body.merge(issues: body[:issues].map { |issue| transform_issue_path(issue) })
+        end
+
+        def transform_issue_path(issue)
+          return issue unless issue.is_a?(Hash)
+
+          result = issue.dup
+          result[:path] = transform_path_segments(result[:path]) if result[:path].is_a?(Array)
+          result[:pointer] = transform_pointer_segments(result[:pointer]) if result[:pointer].is_a?(String)
+          result
+        end
+
+        def transform_path_segments(segments)
+          segments.map { |segment| segment.is_a?(String) ? transform_key(segment) : segment }
+        end
+
+        def transform_pointer_segments(pointer)
+          pointer.split('/').map { |segment| segment.empty? ? segment : transform_key(segment) }.join('/')
+        end
+
         def extract_namespaces(mount_path)
           return [] if mount_path.nil? || mount_path == '/'
 

data/lib/apiwork/api/object.rb

@@ -36,8 +36,8 @@ module Apiwork
       #   The param type.
       # @param as [Symbol, nil] (nil)
       #   The target attribute name.
-      # @param default [Object, nil] (nil)
-      #   The default value.
+      # @param default [Object] (UNSET)
+      #   The default value. Omit to declare no default. Pass `nil` for an explicit null default. A param with a default is always optional.
       # @param deprecated [Boolean] (false)
       #   Whether deprecated. Metadata included in exports.
       # @param description [String, nil] (nil)
@@ -61,7 +61,7 @@ module Apiwork
       # @param of [Symbol, Hash, nil] (nil)
       #   The element or value type. Arrays and records only.
       # @param optional [Boolean] (false)
-      #   Whether the param is optional.
+      #   Whether the param is optional. Always `true` for params with a `default`.
       # @param required [Boolean] (false)
       #   Whether the param is required.
       # @param shape [API::Object, API::Union, nil] (nil)
@@ -86,7 +86,7 @@ module Apiwork
         type: nil,
         as: nil,
         custom_type: nil,
-        default: nil,
+        default: UNSET,
         deprecated: false,
         description: nil,
         discriminator: nil,
@@ -103,6 +103,7 @@ module Apiwork
         value: nil,
         &block
       )
+        optional = normalize_optional(optional, default)
         resolved_of = resolve_of(of, type, &block)
         resolved_shape = [:array, :record].include?(type) ? nil : (shape || build_shape(type, discriminator, &block))
         discriminator = resolved_of&.discriminator if type == :array
@@ -110,7 +111,6 @@ module Apiwork
         param_hash = {
           as:,
           custom_type:,
-          default:,
           deprecated:,
           description:,
           discriminator:,
@@ -126,10 +126,11 @@ module Apiwork
           type:,
           value:,
           of: resolved_of,
-        }
+        }.compact
+        param_hash[:default] = default unless UNSET.equal?(default)
         param_hash[:shape] = resolved_shape if resolved_shape
 
-        @params[name] = (@params[name] || {}).merge(param_hash.compact)
+        @params[name] = (@params[name] || {}).merge(param_hash)
       end
 
       # @api public
@@ -139,8 +140,8 @@ module Apiwork
       #   The param name.
       # @param as [Symbol, nil] (nil)
       #   The target attribute name.
-      # @param default [Object, nil] (nil)
-      #   The default value.
+      # @param default [Object] (UNSET)
+      #   The default value. Omit to declare no default. Pass `nil` for an explicit null default. A param with a default is always optional.
       # @param deprecated [Boolean] (false)
       #   Whether deprecated. Metadata included in exports.
       # @param description [String, nil] (nil)
@@ -148,7 +149,7 @@ module Apiwork
       # @param nullable [Boolean] (false)
       #   Whether the value can be `null`.
       # @param optional [Boolean] (false)
-      #   Whether the param is optional.
+      #   Whether the param is optional. Always `true` for params with a `default`.
       # @param required [Boolean] (false)
       #   Whether the param is required.
       # @yield block for defining element type
@@ -167,7 +168,7 @@ module Apiwork
       def array(
         name,
         as: nil,
-        default: nil,
+        default: UNSET,
         deprecated: false,
         description: nil,
         nullable: false,
@@ -202,8 +203,8 @@ module Apiwork
       #   The param name.
       # @param as [Symbol, nil] (nil)
       #   The target attribute name.
-      # @param default [Object, nil] (nil)
-      #   The default value.
+      # @param default [Object] (UNSET)
+      #   The default value. Omit to declare no default. Pass `nil` for an explicit null default. A param with a default is always optional.
       # @param deprecated [Boolean] (false)
       #   Whether deprecated. Metadata included in exports.
       # @param description [String, nil] (nil)
@@ -211,7 +212,7 @@ module Apiwork
       # @param nullable [Boolean] (false)
       #   Whether the value can be `null`.
       # @param optional [Boolean] (false)
-      #   Whether the param is optional.
+      #   Whether the param is optional. Always `true` for params with a `default`.
       # @param required [Boolean] (false)
       #   Whether the param is required.
       # @yield block for defining value type
@@ -230,7 +231,7 @@ module Apiwork
       def record(
         name,
         as: nil,
-        default: nil,
+        default: UNSET,
         deprecated: false,
         description: nil,
         nullable: false,

data/lib/apiwork/contract/object/validator.rb

@@ -76,7 +76,7 @@ module Apiwork
           required_error = validate_required(name, value, param_options, data, field_path)
           return [[required_error], NOT_SET] if required_error
 
-          value = param_options[:default] if value.nil? && param_options[:default]
+          value = param_options[:default] if value.nil? && param_options.key?(:default)
 
           nullable_error = validate_nullable(name, value, param_options, data, field_path)
           return [[nullable_error], NOT_SET] if nullable_error

data/lib/apiwork/contract/object.rb

@@ -60,8 +60,8 @@ module Apiwork
       #   The param type.
       # @param as [Symbol, nil] (nil)
       #   The target attribute name.
-      # @param default [Object, nil] (nil)
-      #   The default value.
+      # @param default [Object] (UNSET)
+      #   The default value. Omit to declare no default. Pass `nil` for an explicit null default. A param with a default is always optional.
       # @param deprecated [Boolean] (false)
       #   Whether deprecated. Metadata included in exports.
       # @param description [String, nil] (nil)
@@ -85,7 +85,7 @@ module Apiwork
       # @param of [Symbol, Hash, nil] (nil)
       #   The element or value type. Arrays and records only.
       # @param optional [Boolean] (false)
-      #   Whether the param is optional.
+      #   Whether the param is optional. Always `true` for params with a `default`.
       # @param required [Boolean] (false)
       #   Whether the param is required.
       # @param shape [Contract::Object, Contract::Union, nil] (nil)
@@ -110,7 +110,7 @@ module Apiwork
         type: nil,
         as: nil,
         custom_type: nil,
-        default: nil,
+        default: UNSET,
         deprecated: false,
         description: nil,
         discriminator: nil,
@@ -140,6 +140,8 @@ module Apiwork
 
         raise ConfigurationError, 'discriminator can only be used with type: :union' if discriminator && type != :union
 
+        optional = normalize_optional(optional, default)
+
         visited_types ||= @visited_types
         visited_types ||= Set.new
 
@@ -183,8 +185,8 @@ module Apiwork
       #   The param name.
       # @param as [Symbol, nil] (nil)
       #   The target attribute name.
-      # @param default [Object, nil] (nil)
-      #   The default value.
+      # @param default [Object] (UNSET)
+      #   The default value. Omit to declare no default. Pass `nil` for an explicit null default. A param with a default is always optional.
       # @param deprecated [Boolean] (false)
       #   Whether deprecated. Metadata included in exports.
       # @param description [String, nil] (nil)
@@ -196,7 +198,7 @@ module Apiwork
       # @param nullable [Boolean] (false)
       #   Whether the value can be `null`.
       # @param optional [Boolean] (false)
-      #   Whether the param is optional.
+      #   Whether the param is optional. Always `true` for params with a `default`.
       # @param required [Boolean] (false)
       #   Whether the param is required.
       # @yield block for defining element type
@@ -215,7 +217,7 @@ module Apiwork
       def array(
         name,
         as: nil,
-        default: nil,
+        default: UNSET,
         deprecated: false,
         description: nil,
         max: nil,
@@ -254,8 +256,8 @@ module Apiwork
       #   The param name.
       # @param as [Symbol, nil] (nil)
       #   The target attribute name.
-      # @param default [Object, nil] (nil)
-      #   The default value.
+      # @param default [Object] (UNSET)
+      #   The default value. Omit to declare no default. Pass `nil` for an explicit null default. A param with a default is always optional.
       # @param deprecated [Boolean] (false)
       #   Whether deprecated. Metadata included in exports.
       # @param description [String, nil] (nil)
@@ -263,7 +265,7 @@ module Apiwork
       # @param nullable [Boolean] (false)
       #   Whether the value can be `null`.
       # @param optional [Boolean] (false)
-      #   Whether the param is optional.
+      #   Whether the param is optional. Always `true` for params with a `default`.
       # @param required [Boolean] (false)
       #   Whether the param is required.
       # @yield block for defining value type
@@ -282,7 +284,7 @@ module Apiwork
       def record(
         name,
         as: nil,
-        default: nil,
+        default: UNSET,
         deprecated: false,
         description: nil,
         nullable: false,
@@ -395,18 +397,18 @@ module Apiwork
       def define_literal_param(name, as:, default:, deprecated:, description:, optional:, value:)
         raise ConfigurationError, 'Literal type requires a value parameter' if value.nil?
 
-        @params[name] = (@params[name] || {}).merge(
-          {
-            as:,
-            default:,
-            deprecated:,
-            description:,
-            name:,
-            optional:,
-            value:,
-            type: :literal,
-          }.compact,
-        )
+        params = {
+          as:,
+          deprecated:,
+          description:,
+          name:,
+          optional:,
+          value:,
+          type: :literal,
+        }.compact
+        params[:default] = default unless UNSET.equal?(default)
+
+        @params[name] = (@params[name] || {}).merge(params)
       end
 
       def define_union_param(name, as:, default:, discriminator:, optional:, options:, resolved_enum:, &block)
@@ -415,19 +417,19 @@ module Apiwork
         union = Union.new(@contract_class, discriminator:)
         block.arity.positive? ? yield(union) : union.instance_eval(&block)
 
-        @params[name] = (@params[name] || {}).merge(
-          {
-            as:,
-            default:,
-            discriminator:,
-            enum: resolved_enum,
-            name:,
-            optional:,
-            type: :union,
-            union:,
-            **options,
-          }.compact,
-        )
+        params = {
+          as:,
+          discriminator:,
+          enum: resolved_enum,
+          name:,
+          optional:,
+          type: :union,
+          union:,
+          **options,
+        }.compact
+        params[:default] = default unless UNSET.equal?(default)
+
+        @params[name] = (@params[name] || {}).merge(params)
       end
 
       def define_regular_param(name, as:, default:, of:, optional:, options:, resolved_enum:, shape:, type:, visited_types:, &block)
@@ -514,20 +516,20 @@ module Apiwork
           end
         end
 
-        @params[name] = (@params[name] || {}).merge(
-          {
-            as:,
-            custom_type: type,
-            default:,
-            discriminator: type_definition.discriminator,
-            enum: resolved_enum,
-            name:,
-            optional:,
-            type: :union,
-            union:,
-            **options,
-          }.compact,
-        )
+        params = {
+          as:,
+          custom_type: type,
+          discriminator: type_definition.discriminator,
+          enum: resolved_enum,
+          name:,
+          optional:,
+          type: :union,
+          union:,
+          **options,
+        }.compact
+        params[:default] = default unless UNSET.equal?(default)
+
+        @params[name] = (@params[name] || {}).merge(params)
       end
 
       def define_custom_type_param(
@@ -557,38 +559,38 @@ module Apiwork
           block.arity.positive? ? yield(shape) : shape.instance_eval(&block)
         end
 
-        @params[name] = (@params[name] || {}).merge(
-          {
-            as:,
-            custom_type: type,
-            default:,
-            enum: resolved_enum,
-            name:,
-            of:,
-            optional:,
-            shape:,
-            type: :object,
-            **options,
-          }.compact,
-        )
+        params = {
+          as:,
+          custom_type: type,
+          enum: resolved_enum,
+          name:,
+          of:,
+          optional:,
+          shape:,
+          type: :object,
+          **options,
+        }.compact
+        params[:default] = default unless UNSET.equal?(default)
+
+        @params[name] = (@params[name] || {}).merge(params)
       end
 
       def define_standard_param(name, as:, default:, of:, optional:, options:, resolved_enum:, shape:, type:, &block)
         resolved_of = resolve_of(of, type, &block)
         resolved_shape = resolve_shape(shape, type, &block)
 
-        @params[name] = (@params[name] || {}).merge(
-          {
-            as:,
-            default:,
-            enum: resolved_enum,
-            name:,
-            of: resolved_of,
-            optional:,
-            type:,
-            **options,
-          }.compact,
-        )
+        params = {
+          as:,
+          enum: resolved_enum,
+          name:,
+          of: resolved_of,
+          optional:,
+          type:,
+          **options,
+        }.compact
+        params[:default] = default unless UNSET.equal?(default)
+
+        @params[name] = (@params[name] || {}).merge(params)
 
         @params[name][:shape] = resolved_shape if resolved_shape
       end

data/lib/apiwork/controller.rb

@@ -245,8 +245,12 @@ module Apiwork
 
     def render_error(error)
       representation_class = resource ? contract_class.representation_class : nil
-      json = adapter.process_error(error, representation_class, context:)
-      render json:, status: error.status
+      body = adapter.process_error(error, representation_class, context:)
+
+      response = Response.new(body:)
+      response = api_class.prepare_error_response(response)
+
+      render json: response.body, status: error.status
     end
 
     def contract_class

data/lib/apiwork/export/apiwork.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Export
+    class Apiwork < Base
+      export_name :apiwork
+      output :hash
+
+      def generate
+        ApiworkMapper.map(self, surface)
+      end
+
+      private
+
+      def surface
+        @surface ||= SurfaceResolver.resolve(api)
+      end
+    end
+  end
+end