apiwork 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e82aa84563a02e2459a6d464c65cd50e5bb3edcb762a0a5b9412e79475663c52
-  data.tar.gz: ac7da6d7f57a6be553fa8809da6f449029ac9d9c42e4da24c780e9f4364c1a4a
+  metadata.gz: 7614067b7732803415ef2038394b28590c02e63734cdf9b879aab126dcb1caee
+  data.tar.gz: 2a7399c16a27c51c64e92811e7c020b863de65e4fdaaa7f4e400d7c8c308a94b
 SHA512:
-  metadata.gz: 4f7bd06c06cb8485762e066e8efb64d21af6258b85442bbbc9813b1359e3d38706314dd285fe48de42d8a5526590c08508c436abdb8acfe0c23c203ade8391db
-  data.tar.gz: 7ce587bd8232382e56a8f5da4ba33d1dd942482e018e1e968aacb1f1a6be8bb778d85dec4ee425799a350b0afdd7a4c7277c264b661209bb16f6404e7ec9bf32
+  metadata.gz: 58e21417d9e0fa2e6d4bd05106f4619282fc2925af365433902392f2d841eda8e4035ffb4800e0dbd96a09cf513a507237b6ec0bb31de2f648c48d8e6bd00b38
+  data.tar.gz: de1ce6873f0c20373ce9bab1cd8e70b4b1787b6ae9adbf2f5fcb1c65720df33e45ad05aea524a8720837a777b7e50059c8a9d02240a1ddff57e9d69ad6422caf

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/serializer/resource/default/contract_builder.rb

@@ -59,6 +59,8 @@ module Apiwork
                 end
 
                 representation_class.attributes.each do |name, attribute|
+                  next if attribute.write_only?
+
                   param_options = {
                     deprecated: attribute.deprecated?,
                     description: attribute.description,

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.
       # @param deprecated [Boolean] (false)
       #   Whether deprecated. Metadata included in exports.
       # @param description [String, 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,
@@ -110,7 +110,6 @@ module Apiwork
         param_hash = {
           as:,
           custom_type:,
-          default:,
           deprecated:,
           description:,
           discriminator:,
@@ -126,10 +125,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 +139,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.
       # @param deprecated [Boolean] (false)
       #   Whether deprecated. Metadata included in exports.
       # @param description [String, nil] (nil)
@@ -167,7 +167,7 @@ module Apiwork
       def array(
         name,
         as: nil,
-        default: nil,
+        default: UNSET,
         deprecated: false,
         description: nil,
         nullable: false,
@@ -202,8 +202,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.
       # @param deprecated [Boolean] (false)
       #   Whether deprecated. Metadata included in exports.
       # @param description [String, nil] (nil)
@@ -230,7 +230,7 @@ module Apiwork
       def record(
         name,
         as: nil,
-        default: nil,
+        default: UNSET,
         deprecated: false,
         description: nil,
         nullable: false,

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.
       # @param deprecated [Boolean] (false)
       #   Whether deprecated. Metadata included in exports.
       # @param description [String, 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,
@@ -183,8 +183,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.
       # @param deprecated [Boolean] (false)
       #   Whether deprecated. Metadata included in exports.
       # @param description [String, nil] (nil)
@@ -215,7 +215,7 @@ module Apiwork
       def array(
         name,
         as: nil,
-        default: nil,
+        default: UNSET,
         deprecated: false,
         description: nil,
         max: nil,
@@ -254,8 +254,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.
       # @param deprecated [Boolean] (false)
       #   Whether deprecated. Metadata included in exports.
       # @param description [String, nil] (nil)
@@ -282,7 +282,7 @@ module Apiwork
       def record(
         name,
         as: nil,
-        default: nil,
+        default: UNSET,
         deprecated: false,
         description: nil,
         nullable: false,
@@ -395,18 +395,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 +415,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 +514,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 +557,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

data/lib/apiwork/export/apiwork_mapper.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Export
+    class ApiworkMapper
+      class << self
+        def map(export, surface)
+          new(export).map(surface)
+        end
+      end
+
+      def initialize(export)
+        @export = export
+      end
+
+      def map(surface)
+        {
+          base_path: @export.api.base_path,
+          enums: serialize_enums(surface.enums),
+          error_codes: serialize_error_codes,
+          fingerprint: @export.api.fingerprint,
+          info: serialize_info,
+          locales: @export.api.locales.map(&:to_s),
+          resources: serialize_resources(@export.api.resources),
+          types: serialize_types(surface.types),
+        }
+      end
+
+      private
+
+      def serialize_enums(enums)
+        enums.map do |name, enum|
+          {
+            deprecated: enum.deprecated?,
+            description: enum.description,
+            example: enum.example,
+            name: name.to_s,
+            scope: enum.scope,
+            values: enum.values,
+          }
+        end
+      end
+
+      def serialize_error_codes
+        @export.api.error_codes.map do |name, error_code|
+          {
+            description: error_code.description,
+            name: name.to_s,
+            status: error_code.status,
+          }
+        end
+      end
+
+      def serialize_info
+        info = @export.api.info
+        return unless info
+
+        {
+          contact: info.contact && {
+            email: info.contact.email,
+            name: info.contact.name,
+            url: info.contact.url,
+          },
+          description: info.description,
+          license: info.license && {
+            name: info.license.name,
+            url: info.license.url,
+          },
+          servers: info.servers.map do |server|
+            { description: server.description, url: server.url }
+          end,
+          summary: info.summary,
+          terms_of_service: info.terms_of_service,
+          title: info.title,
+          version: info.version,
+        }
+      end
+
+      def serialize_types(types)
+        type_hashes = types.transform_values(&:to_h)
+        sorted = TypeAnalysis.topological_sort_types(type_hashes)
+        recursive = TypeAnalysis.cycle_breaking_types(type_hashes)
+
+        sorted.map { |name, _| serialize_type(name, types[name], recursive: recursive.include?(name)) }
+      end
+
+      def serialize_type(name, type, recursive:)
+        result = {
+          recursive:,
+          deprecated: type.deprecated?,
+          description: type.description,
+          example: type.example,
+          name: name.to_s,
+          scope: type.scope,
+          type: type.type.to_s,
+        }
+
+        if type.object?
+          result[:extends] = type.extends.map(&:to_s)
+          result[:shape] = serialize_shape(type.shape)
+        else
+          result[:discriminator] = transform_key(type.discriminator)
+          result[:variants] = type.variants.map do |variant|
+            serialized = serialize_param(variant)
+            serialized[:tag] = variant.tag if variant.respond_to?(:tag) && variant.tag
+            serialized
+          end
+        end
+
+        result
+      end
+
+      def serialize_resources(resources, prefix: nil)
+        resources.map do |name, resource|
+          qualified_name = prefix ? "#{prefix}.#{name}" : name.to_s
+
+          {
+            actions: resource.actions.map do |action_name, action|
+              serialize_action(action, name: "#{qualified_name}.#{action_name}")
+            end,
+            identifier: resource.identifier.to_s,
+            name: name.to_s,
+            parent_identifiers: resource.parent_identifiers.map(&:to_s),
+            path: transform_path(resource.path),
+            resources: serialize_resources(resource.resources, prefix: qualified_name),
+            scope: resource.scope,
+          }
+        end
+      end
+
+      def serialize_action(action, name:)
+        {
+          name:,
+          deprecated: action.deprecated?,
+          description: action.description,
+          method: action.method.to_s,
+          operation_id: action.operation_id,
+          path: transform_path(action.path),
+          raises: action.raises.map(&:to_s),
+          request: {
+            body: serialize_shape(action.request.body),
+            description: action.request.description,
+            query: serialize_shape(action.request.query),
+          },
+          response: {
+            body: serialize_response_body(action.response),
+            description: action.response.description,
+            no_content: action.response.no_content?,
+          },
+          summary: action.summary,
+          tags: action.tags,
+        }
+      end
+
+      def serialize_response_body(response)
+        return unless response.body?
+
+        serialize_param(response.body)
+      end
+
+      def serialize_shape(params)
+        params.sort_by { |name, _| name.to_s }.map do |name, param|
+          { name: transform_key(name) }.merge(serialize_param(param))
+        end
+      end
+
+      def serialize_param(param)
+        result = {
+          deprecated: param.deprecated?,
+          description: param.description,
+          nullable: param.nullable?,
+          optional: param.optional?,
+          type: param.type.to_s,
+        }
+
+        case param.type
+        when :string, :integer
+          result[:default] = param.default if param.default?
+          result[:enum] = param.enum.to_s if param.enum?
+          result[:example] = param.example
+          result[:format] = param.format
+          result[:max] = param.max
+          result[:min] = param.min
+        when :number, :decimal
+          result[:default] = param.default if param.default?
+          result[:enum] = param.enum.to_s if param.enum?
+          result[:example] = param.example
+          result[:max] = param.max
+          result[:min] = param.min
+        when :boolean, :date, :datetime, :time, :uuid, :binary
+          result[:default] = param.default if param.default?
+          result[:enum] = param.enum.to_s if param.enum?
+          result[:example] = param.example
+        when :literal
+          result[:value] = param.value
+        when :array
+          result[:default] = param.default if param.default?
+          result[:example] = param.example
+          result[:max] = param.max
+          result[:min] = param.min
+          result[:of] = param.of ? serialize_param(param.of) : nil
+        when :record
+          result[:default] = param.default if param.default?
+          result[:example] = param.example
+          result[:of] = param.of ? serialize_param(param.of) : nil
+        when :object
+          result[:partial] = param.partial?
+          result[:shape] = serialize_shape(param.shape)
+        when :union
+          result[:discriminator] = transform_key(param.discriminator)
+          result[:variants] = param.variants.map do |variant|
+            serialized = serialize_param(variant)
+            serialized[:tag] = variant.tag if variant.respond_to?(:tag) && variant.tag
+            serialized
+          end
+        when :reference
+          result[:reference] = param.reference.to_s
+        end
+
+        result
+      end
+
+      def transform_path(path)
+        path.to_s.gsub(/:(\w+)/) { ":#{transform_key(::Regexp.last_match(1))}" }
+      end
+
+      def transform_key(key)
+        @export.transform_key(key)
+      end
+    end
+  end
+end

data/lib/apiwork/export/open_api.rb

@@ -324,6 +324,8 @@ module Apiwork
 
         schema[:format] = param.format.to_s if param.formattable? && param.format
 
+        schema[:default] = param.default if param.respond_to?(:default) && param.default?
+
         apply_nullable(schema, param.nullable?)
       end
 

data/lib/apiwork/export/registry.rb

@@ -2,7 +2,7 @@
 
 module Apiwork
   module Export
-    class Registry < Apiwork::Registry
+    class Registry < ::Apiwork::Registry
       class << self
         def register(export_class)
           raise ArgumentError, 'Export must inherit from Apiwork::Export::Base' unless export_class < Base