apiwork 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14f70185b89b359e58791101591102755c5e523fed61fe4e4cdf7e5ad3cd1615
-  data.tar.gz: 10303ee74f360fa49fd711497dec982094cd7d3f7621d08a47c68abecf22bd3f
+  metadata.gz: eb5f681a0f08e4bebe2d0f5ebf4edac733f3787e4144f019bc4babfa7a7ef84a
+  data.tar.gz: e5d1d87115d2902295d66567c324d73ef15d01b0ac106c1fa9739b56a276aeb3
 SHA512:
-  metadata.gz: cb799505dac690b1807a31f3c6f87d5b4893d85ba79f007966a2e6bfe19c58e2e63a0bf6bed4080de6b8c7a1aee3fbd9deab76f4fbabf8c416ff9ab9e78598b6
-  data.tar.gz: 0bfe2378cfc17aab81dd0af3ccd1fff1e0bbafad476e97e9c71f0b2c7764485d2f02f44290a7c9015d2ada479ae2b37d00c76786369515361a424688cb1b390a
+  metadata.gz: bb539d87fcd3b065d643711616f7f9f5589d574cbf12bcc06c69aafe7000f6fafa4e19d7fd34cd165d2734076d3b192472a6f51459074241fabbf5dd3faece42
+  data.tar.gz: 692745d73d86c3f5c377ae2a7962b38efe351b1fc893df6af45bd8de025622f61257307dedcd1b6aac15df8f3112874e92c54d3b3e316ef9aaa59ef6fcca0338

data/README.md

@@ -1,5 +1,13 @@
 # Apiwork
 
+[![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)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+![OpenAPI](https://img.shields.io/badge/OpenAPI-exports-6BA539?logo=openapiinitiative&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-exports-3178C6?logo=typescript&logoColor=white)
+![Zod](https://img.shields.io/badge/Zod-exports-3068B7?logo=zod&logoColor=white)
+
 Typed APIs for Rails.
 
 Apiwork lets you define your API once and derive validation, serialization, querying, and typed exports from the same definition.

data/lib/apiwork/adapter/base.rb

@@ -210,18 +210,16 @@ module Apiwork
 
         error_serializer_class = self.class.error_serializer
         error_serializer_class.new.api_types(api_class)
-
-        build_error_response_body(api_class, error_serializer_class)
       end
 
-      def register_contract(contract_class, representation_class, actions)
+      def register_contract(contract_class, representation_class, resource_actions: {})
         capabilities.each do |capability|
-          capability.contract_types(contract_class, representation_class, actions)
+          capability.contract_types(contract_class, representation_class, resource_actions)
         end
 
         self.class.resource_serializer.new(representation_class).contract_types(contract_class)
 
-        build_action_responses(contract_class, representation_class, actions)
+        build_action_responses(contract_class, representation_class, resource_actions) if resource_actions.any?
       end
 
       def apply_request_transformers(request, phase:)
@@ -250,8 +248,8 @@ module Apiwork
         )
       end
 
-      def build_action_responses(contract_class, representation_class, actions)
-        actions.each_value do |action|
+      def build_action_responses(contract_class, representation_class, resource_actions)
+        resource_actions.each_value do |action|
           build_action_response(contract_class, representation_class, action)
         end
       end
@@ -273,12 +271,10 @@ module Apiwork
       end
 
       def build_member_action_response(contract_class, representation_class, action, contract_action)
-        result_wrapper = build_result_wrapper(contract_class, representation_class, action.name, :member)
         member_shape_class = self.class.member_wrapper.shape_class
         data_type = resolve_resource_data_type(representation_class)
 
         contract_action.response do |response|
-          response.result_wrapper = result_wrapper
           response.body do |body|
             member_shape_class.apply(body, representation_class.root_key, capabilities, representation_class, :member, data_type:)
           end
@@ -286,12 +282,10 @@ module Apiwork
       end
 
       def build_collection_action_response(contract_class, representation_class, action, contract_action)
-        result_wrapper = build_result_wrapper(contract_class, representation_class, action.name, :collection)
         collection_shape_class = self.class.collection_wrapper.shape_class
         data_type = resolve_resource_data_type(representation_class)
 
         contract_action.response do |response|
-          response.result_wrapper = result_wrapper
           response.body do |body|
             collection_shape_class.apply(body, representation_class.root_key, capabilities, representation_class, :collection, data_type:)
           end
@@ -308,42 +302,10 @@ module Apiwork
         end
       end
 
-      def build_result_wrapper(contract_class, representation_class, action_name, response_type)
-        success_type_name = [action_name, 'success_response_body'].join('_').to_sym
-
-        unless contract_class.type?(success_type_name)
-          shape_class = if response_type == :collection
-                          self.class.collection_wrapper.shape_class
-                        else
-                          self.class.member_wrapper.shape_class
-                        end
-          data_type = resolve_resource_data_type(representation_class)
-
-          contract_class.object(success_type_name) do |object|
-            shape_class.apply(object, representation_class.root_key, capabilities, representation_class, response_type, data_type:)
-          end
-        end
-
-        { error_type: :error_response_body, success_type: contract_class.scoped_type_name(success_type_name) }
-      end
-
       def resolve_resource_data_type(representation_class)
         self.class.resource_serializer.data_type.call(representation_class)
       end
 
-      def build_error_response_body(api_class, error_serializer_class)
-        return if api_class.type?(:error_response_body)
-
-        shape_class = self.class.error_wrapper.shape_class
-        return unless shape_class
-
-        data_type = error_serializer_class.data_type
-
-        api_class.object(:error_response_body) do |object|
-          shape_class.apply(object, nil, [], nil, :error, data_type:)
-        end
-      end
-
       def run_capability_request_transformers(request, phase:)
         transformers = capability_request_transformers.select { |transformer_class| transformer_class.phase == phase }
         result = request

data/lib/apiwork/api/base.rb

@@ -727,9 +727,9 @@ module Apiwork
           @built_contracts.add(contract_class)
 
           resource = @root_resource.find_resource { |resource| resource.resolve_contract_class == contract_class }
-          actions = resource ? resource.actions : {}
+          resource_actions = resource ? resource.actions : {}
 
-          adapter.register_contract(contract_class, representation_class, actions)
+          adapter.register_contract(contract_class, representation_class, resource_actions:)
         end
 
         def ensure_pre_pass_complete!
@@ -788,13 +788,11 @@ module Apiwork
           contract_class = resource.resolve_contract_class
           return unless contract_class
           return if @built_contracts.include?(contract_class)
-
-          representation_class = contract_class.representation_class
-          return unless representation_class
+          return unless contract_class.representation_class
 
           @built_contracts.add(contract_class)
 
-          adapter.register_contract(contract_class, representation_class, resource.actions)
+          adapter.register_contract(contract_class, contract_class.representation_class, resource_actions: resource.actions)
         end
       end
     end

data/lib/apiwork/contract/action/request.rb

@@ -16,6 +16,28 @@ module Apiwork
           @action_name = action_name
           @query = nil
           @body = nil
+          @description = nil
+        end
+
+        # @api public
+        # The description for this request.
+        #
+        # Metadata included in exports.
+        #
+        # @param value [String, nil] (nil)
+        #   The description.
+        # @return [String, nil]
+        #
+        # @example
+        #   action :create do
+        #     request do
+        #       description 'The invoice to create'
+        #     end
+        #   end
+        def description(value = nil)
+          return @description if value.nil?
+
+          @description = value
         end
 
         # @api public

data/lib/apiwork/contract/action/response.rb

@@ -11,16 +11,35 @@ module Apiwork
         attr_reader :action_name,
                     :contract_class
 
-        attr_accessor :result_wrapper
-
         def initialize(contract_class, action_name)
           @contract_class = contract_class
           @action_name = action_name
           @body = nil
-          @result_wrapper = nil
+          @description = nil
           @no_content = false
         end
 
+        # @api public
+        # The description for this response.
+        #
+        # Metadata included in exports.
+        #
+        # @param value [String, nil] (nil)
+        #   The description.
+        # @return [String, nil]
+        #
+        # @example
+        #   action :show do
+        #     response do
+        #       description 'Returns the invoice'
+        #     end
+        #   end
+        def description(value = nil)
+          return @description if value.nil?
+
+          @description = value
+        end
+
         # @api public
         # Whether this response has no content.
         #

data/lib/apiwork/export/open_api.rb

@@ -106,7 +106,11 @@ module Apiwork
           query_params = request.query? ? build_query_parameters(request.query) : []
           all_params = path_params + query_params
           operation[:parameters] = all_params if all_params.any?
-          operation[:requestBody] = build_request_body(request.body) if request.body?
+          if request.body?
+            request_body = build_request_body(request.body)
+            request_body[:description] = request.description if request.description
+            operation[:requestBody] = request_body
+          end
         elsif path_params.any?
           operation[:parameters] = path_params
         end
@@ -200,42 +204,23 @@ module Apiwork
       def build_responses(action_name, response, raises: [])
         responses = {}
 
+        response_description = response.description || ''
+
         if response.no_content?
-          responses[:'204'] = { description: 'No content' }
+          responses[:'204'] = { description: response_description }
         elsif response.body
-          body = response.body
-
-          if body.union? && body.discriminator.nil?
-            success_variant = body.variants[0]
-            error_variant = body.variants[1]
-
-            responses[:'200'] = {
-              content: {
-                'application/json': {
-                  schema: map_param(success_variant),
-                },
-              },
-              description: 'Successful response',
-            }
-
-            raises.each do |code|
-              error_code = api.error_codes[code]
-              responses[error_code.status.to_s.to_sym] = build_union_error_response(error_code.description, error_variant)
-            end
-          else
-            responses[:'200'] = {
-              content: {
-                'application/json': {
-                  schema: map_param(body),
-                },
+          responses[:'200'] = {
+            content: {
+              'application/json': {
+                schema: map_param(response.body),
               },
-              description: 'Successful response',
-            }
+            },
+            description: response_description,
+          }
 
-            raises.each do |code|
-              error_code = api.error_codes[code]
-              responses[error_code.status.to_s.to_sym] = build_error_response(error_code.description)
-            end
+          raises.each do |code|
+            error_code = api.error_codes[code]
+            responses[error_code.status.to_s.to_sym] = build_error_response(error_code.description)
           end
         elsif response
           responses[:'200'] = {
@@ -249,10 +234,10 @@ module Apiwork
                 },
               },
             },
-            description: 'Successful response',
+            description: response_description,
           }
         else
-          responses[:'204'] = { description: 'No content' }
+          responses[:'204'] = { description: '' }
         end
 
         responses
@@ -280,17 +265,6 @@ module Apiwork
         }
       end
 
-      def build_union_error_response(description, error_variant)
-        {
-          description:,
-          content: {
-            'application/json': {
-              schema: map_param(error_variant),
-            },
-          },
-        }
-      end
-
       def surface
         @surface ||= SurfaceResolver.resolve(api)
       end

data/lib/apiwork/export/sorbus.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Export
+    class Sorbus < Base
+      export_name :sorbus
+      output :string
+      file_extension '.ts'
+
+      def generate
+        SorbusMapper.map(self, surface)
+      end
+
+      private
+
+      def surface
+        @surface ||= SurfaceResolver.resolve(api)
+      end
+    end
+  end
+end

data/lib/apiwork/export/sorbus_mapper.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Export
+    class SorbusMapper
+      class << self
+        def map(export, surface)
+          new(export).map(surface)
+        end
+      end
+
+      def initialize(export)
+        @export = export
+        @zod_mapper = ZodMapper.new(export)
+        @type_script_mapper = TypeScriptMapper.new(export)
+      end
+
+      def map(surface)
+        @surface = surface
+
+        [
+          "import { z } from 'zod';",
+          @zod_mapper.build_enum_schemas(surface.enums).presence,
+          @zod_mapper.build_type_schemas(surface.types).presence,
+          build_typescript_types.presence,
+          build_contract,
+        ].compact.join("\n\n")
+      end
+
+      private
+
+      def build_typescript_types
+        types = @type_script_mapper.build_enum_types(@surface.enums) +
+                @type_script_mapper.build_type_definitions(@surface.types)
+
+        types.sort_by { |entry| entry[:name] }.map { |entry| entry[:code] }.join("\n\n")
+      end
+
+      def build_contract
+        contract = {
+          endpoints: build_endpoint_tree(@export.api.resources),
+          error: build_error_schema,
+        }
+        "export const contract = #{format_object(contract, indent: 0)} as const;"
+      end
+
+      def build_endpoint_tree(resources, parent_identifiers: [])
+        resources.each_with_object({}) do |(name, resource), tree|
+          resource_key = @export.transform_key(name)
+          identifiers = parent_identifiers + [resource.identifier]
+
+          endpoints = resource.actions.each_with_object({}) do |(action_name, action), actions|
+            actions[@export.transform_key(action_name)] = build_endpoint(
+              resource.identifier.to_sym, action_name, action
+            )
+          end
+
+          endpoints.merge!(build_endpoint_tree(resource.resources, parent_identifiers: identifiers))
+          tree[resource_key] = endpoints
+        end
+      end
+
+      def build_endpoint(resource_name, action_name, action)
+        path = transform_path(action.path)
+        endpoint = { path:, method: action.method.to_s.upcase }
+
+        path_params = extract_path_params(action.path)
+        endpoint[:pathParams] = build_path_params_schema(path_params) if path_params.any?
+
+        request = build_request(action.request)
+        endpoint[:request] = request if request
+
+        response = build_response(action.response)
+        endpoint[:response] = response if response
+
+        errors = resolve_errors(action)
+        endpoint[:errors] = errors if errors.any?
+
+        endpoint
+      end
+
+      def transform_path(path)
+        path.gsub(%r{(/:?)(\w+)}) do
+          "#{::Regexp.last_match(1)}#{@export.transform_key(::Regexp.last_match(2))}"
+        end
+      end
+
+      def extract_path_params(path)
+        path.scan(/:(\w+)/).flatten
+      end
+
+      def build_path_params_schema(params)
+        properties = params.map { |param| "#{@export.transform_key(param)}: z.string()" }.join(', ')
+        "z.object({ #{properties} })"
+      end
+
+      def build_request(request)
+        return unless request.query? || request.body?
+
+        hash = {}
+        hash[:query] = build_params_schema(request.query) if request.query?
+        hash[:body] = build_params_schema(request.body) if request.body?
+        hash
+      end
+
+      def build_response(response)
+        return unless response.body?
+
+        { body: @zod_mapper.map_param(response.body) }
+      end
+
+      def build_params_schema(params)
+        properties = params.sort_by { |name, _| name.to_s }.map do |name, param|
+          "#{@export.transform_key(name)}: #{@zod_mapper.map_field(param)}"
+        end.join(', ')
+        "z.object({ #{properties} })"
+      end
+
+      def build_error_schema
+        'ErrorSchema'
+      end
+
+      def resolve_errors(action)
+        action.raises.map { |code| @export.api.error_codes[code].status }.sort.uniq
+      end
+
+      def format_object(hash, indent:)
+        return '{}' if hash.empty?
+
+        padding = '  ' * (indent + 1)
+        closing_padding = '  ' * indent
+
+        entries = hash.map do |key, value|
+          formatted_value = format_value(value, indent: indent + 1)
+          "#{padding}#{key}: #{formatted_value},"
+        end
+
+        "{\n#{entries.join("\n")}\n#{closing_padding}}"
+      end
+
+      def format_value(value, indent:)
+        case value
+        when Hash
+          format_object(value, indent:)
+        when String
+          if value.start_with?('z.') || value.end_with?('Schema')
+            value
+          else
+            "'#{value}'"
+          end
+        when Array
+          "[#{value.join(', ')}]"
+        else
+          value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/export/surface_resolver.rb

@@ -56,6 +56,7 @@ module Apiwork
         action.request.query.each_value { |param| collect_types_from_param(param, type_names) }
         action.request.body.each_value { |param| collect_types_from_param(param, type_names) }
         collect_types_from_param(action.response.body, type_names) if action.response.body
+        type_names << :error if action.raises.any? && @api.types.key?(:error)
       end
 
       def collect_types_from_param(param, type_names)

data/lib/apiwork/export/type_script_mapper.rb

@@ -14,9 +14,10 @@ module Apiwork
       end
 
       def map(surface)
-        types = build_enum_types(surface) +
-                build_type_definitions(surface) +
-                build_action_types
+        types = build_enum_types(surface.enums) +
+                build_type_definitions(surface.types) +
+                build_action_types +
+                build_action_response_types
 
         types.sort_by { |entry| entry[:name] }.map { |entry| entry[:code] }.join("\n\n")
       end
@@ -116,18 +117,25 @@ module Apiwork
         "export type #{action_type_name(resource_name, action_name, 'ResponseBody', parent_identifiers:)} = #{map_param(response_body_definition)};"
       end
 
-      def build_action_response_type(resource_name, action_name, response, parent_identifiers: [])
-        "export interface #{action_type_name(
-          resource_name,
-          action_name,
-          'Response',
-          parent_identifiers:,
-        )} {\n  body: #{action_type_name(
-          resource_name,
-          action_name,
-          'ResponseBody',
-          parent_identifiers:,
-        )};\n}"
+      def build_action_response_type(resource_name, action_name, response, parent_identifiers: [], raises:)
+        type_name = action_type_name(resource_name, action_name, 'Response', parent_identifiers:)
+
+        success_variant = if response.no_content?
+                            '{ status: 204 }'
+                          else
+                            body_ref = action_type_name(resource_name, action_name, 'ResponseBody', parent_identifiers:)
+                            "{ status: 200; body: #{body_ref} }"
+                          end
+
+        error_statuses = resolve_error_statuses(raises)
+
+        if error_statuses.empty?
+          "export type #{type_name} = #{success_variant};"
+        else
+          error_variants = error_statuses.map { |status| "{ status: #{status}; body: #{pascal_case(:error)} }" }
+          all_variants = ([success_variant] + error_variants).map { |variant| "  | #{variant}" }.join("\n")
+          "export type #{type_name} =\n#{all_variants};"
+        end
       end
 
       def action_type_name(resource_name, action_name, suffix, parent_identifiers: [])
@@ -251,23 +259,29 @@ module Apiwork
         end
       end
 
-      private
+      def build_action_types
+        types = []
 
-      def build_enum_types(surface)
-        surface.enums.map do |name, enum|
-          { code: build_enum_type(name, enum), name: pascal_case(name) }
-        end
-      end
+        traverse_resources do |resource|
+          resource_name = resource.identifier.to_sym
+          parent_identifiers = resource.parent_identifiers
 
-      def build_type_definitions(surface)
-        TypeAnalysis.topological_sort_types(surface.types.transform_values(&:to_h)).map(&:first).map do |type_name|
-          type = surface.types[type_name]
-          code = type.union? ? build_union_type(type_name, type) : build_interface(type_name, type)
-          { code:, name: pascal_case(type_name) }
+          resource.actions.each do |action_name, action|
+            types.concat(build_request_types(resource_name, action_name, action.request, parent_identifiers:))
+
+            response = action.response
+            next unless response.body?
+
+            type_name = action_type_name(resource_name, action_name, 'ResponseBody', parent_identifiers:)
+            code = build_action_response_body_type(resource_name, action_name, response.body, parent_identifiers:)
+            types << { code:, name: type_name }
+          end
         end
+
+        types
       end
 
-      def build_action_types
+      def build_action_response_types
         types = []
 
         traverse_resources do |resource|
@@ -275,14 +289,42 @@ module Apiwork
           parent_identifiers = resource.parent_identifiers
 
           resource.actions.each do |action_name, action|
-            types.concat(build_request_types(resource_name, action_name, action.request, parent_identifiers:))
-            types.concat(build_response_types(resource_name, action_name, action.response, parent_identifiers:))
+            type_name = action_type_name(resource_name, action_name, 'Response', parent_identifiers:)
+            code = build_action_response_type(resource_name, action_name, action.response, parent_identifiers:, raises: action.raises)
+            types << { code:, name: type_name }
           end
         end
 
         types
       end
 
+      def traverse_resources(resources: @export.api.resources, &block)
+        resources.each_value do |resource|
+          yield(resource)
+          traverse_resources(resources: resource.resources, &block) if resource.resources.any?
+        end
+      end
+
+      def build_enum_types(enums)
+        enums.map do |name, enum|
+          { code: build_enum_type(name, enum), name: pascal_case(name) }
+        end
+      end
+
+      def build_type_definitions(types)
+        TypeAnalysis.topological_sort_types(types.transform_values(&:to_h)).map(&:first).map do |type_name|
+          type = types[type_name]
+          code = type.union? ? build_union_type(type_name, type) : build_interface(type_name, type)
+          { code:, name: pascal_case(type_name) }
+        end
+      end
+
+      private
+
+      def resolve_error_statuses(raises)
+        raises.map { |code| @export.api.error_codes[code].status }.uniq.sort
+      end
+
       def build_request_types(resource_name, action_name, request, parent_identifiers:)
         types = []
         return types unless request && (request.query? || request.body?)
@@ -306,32 +348,6 @@ module Apiwork
         types
       end
 
-      def build_response_types(resource_name, action_name, response, parent_identifiers:)
-        types = []
-
-        if response.no_content?
-          type_name = action_type_name(resource_name, action_name, 'Response', parent_identifiers:)
-          types << { code: "export type #{type_name} = never;", name: type_name }
-        elsif response.body?
-          type_name = action_type_name(resource_name, action_name, 'ResponseBody', parent_identifiers:)
-          code = build_action_response_body_type(resource_name, action_name, response.body, parent_identifiers:)
-          types << { code:, name: type_name }
-
-          type_name = action_type_name(resource_name, action_name, 'Response', parent_identifiers:)
-          code = build_action_response_type(resource_name, action_name, { body: response.body }, parent_identifiers:)
-          types << { code:, name: type_name }
-        end
-
-        types
-      end
-
-      def traverse_resources(resources: @export.api.resources, &block)
-        resources.each_value do |resource|
-          yield(resource)
-          traverse_resources(resources: resource.resources, &block) if resource.resources.any?
-        end
-      end
-
       def type_or_enum_reference?(symbol)
         @export.api.types.key?(symbol) || @export.api.enums.key?(symbol)
       end

data/lib/apiwork/export/zod_mapper.rb

@@ -28,18 +28,20 @@ module Apiwork
       end
 
       def map(surface)
-        @surface = surface
         parts = []
 
-        enum_schemas = build_enum_schemas
+        enum_schemas = build_enum_schemas(surface.enums)
         parts << enum_schemas if enum_schemas.present?
 
-        type_schemas = build_type_schemas
+        type_schemas = build_type_schemas(surface.types)
         parts << type_schemas if type_schemas.present?
 
         action_schemas = build_action_schemas
         parts << action_schemas if action_schemas.present?
 
+        action_response_schemas = build_action_response_schemas
+        parts << action_response_schemas if action_response_schemas.present?
+
         parts.join("\n\n")
       end
 
@@ -153,18 +155,27 @@ module Apiwork
         "export const #{action_type_name(resource_name, action_name, 'ResponseBody', parent_identifiers:)}Schema = #{map_param(response_body)};"
       end
 
-      def build_action_response_schema(resource_name, action_name, response, parent_identifiers: [])
-        "export const #{action_type_name(
-          resource_name,
-          action_name,
-          'Response',
-          parent_identifiers:,
-        )}Schema = z.object({\n  body: #{action_type_name(
-          resource_name,
-          action_name,
-          'ResponseBody',
-          parent_identifiers:,
-        )}Schema\n});"
+      def build_action_response_schema(resource_name, action_name, response, parent_identifiers: [], raises:)
+        schema_name = action_type_name(resource_name, action_name, 'Response', parent_identifiers:)
+
+        success_variant = if response.no_content?
+                            'z.object({ status: z.literal(204) })'
+                          else
+                            body_ref = "#{action_type_name(resource_name, action_name, 'ResponseBody', parent_identifiers:)}Schema"
+                            "z.object({ status: z.literal(200), body: #{body_ref} })"
+                          end
+
+        error_statuses = resolve_error_statuses(raises)
+
+        if error_statuses.empty?
+          "export const #{schema_name}Schema = #{success_variant};"
+        else
+          error_variants = error_statuses.map do |status|
+            "z.object({ status: z.literal(#{status}), body: #{pascal_case(:error)}Schema })"
+          end
+          all_variants = ([success_variant] + error_variants).map { |variant| "  #{variant}" }.join(",\n")
+          "export const #{schema_name}Schema = z.discriminatedUnion('status', [\n#{all_variants}\n]);"
+        end
       end
 
       def action_type_name(resource_name, action_name, suffix, parent_identifiers: [])
@@ -306,22 +317,20 @@ module Apiwork
         name.to_s.camelize(:upper)
       end
 
-      private
-
-      def build_enum_schemas
-        return '' if @surface.enums.empty?
+      def build_enum_schemas(enums)
+        return '' if enums.empty?
 
-        @surface.enums.map do |name, enum|
+        enums.map do |name, enum|
           "export const #{pascal_case(name)}Schema = z.enum([#{enum.values.sort.map { |value| "'#{value}'" }.join(', ')}]);"
         end.join("\n\n")
       end
 
-      def build_type_schemas
-        types_hash = @surface.types.transform_values(&:to_h)
+      def build_type_schemas(types)
+        types_hash = types.transform_values(&:to_h)
         lazy_types = TypeAnalysis.cycle_breaking_types(types_hash)
 
         TypeAnalysis.topological_sort_types(types_hash).map(&:first).map do |type_name|
-          type = @surface.types[type_name]
+          type = types[type_name]
           recursive = lazy_types.include?(type_name)
 
           if type.union?
@@ -367,12 +376,22 @@ module Apiwork
             end
 
             response = action.response
-            if response.no_content?
-              schemas << "export const #{action_type_name(resource_name, action_name, 'Response', parent_identifiers:)}Schema = z.never();"
-            elsif response.body?
-              schemas << build_action_response_body_schema(resource_name, action_name, response.body, parent_identifiers:)
-              schemas << build_action_response_schema(resource_name, action_name, { body: response.body }, parent_identifiers:)
-            end
+            schemas << build_action_response_body_schema(resource_name, action_name, response.body, parent_identifiers:) if response.body?
+          end
+        end
+
+        schemas.join("\n\n")
+      end
+
+      def build_action_response_schemas
+        schemas = []
+
+        traverse_resources do |resource|
+          resource_name = resource.identifier.to_sym
+          parent_identifiers = resource.parent_identifiers
+
+          resource.actions.each do |action_name, action|
+            schemas << build_action_response_schema(resource_name, action_name, action.response, parent_identifiers:, raises: action.raises)
           end
         end
 
@@ -386,6 +405,8 @@ module Apiwork
         end
       end
 
+      private
+
       def type_or_enum_reference?(symbol)
         @export.api.types.key?(symbol) || @export.api.enums.key?(symbol)
       end
@@ -399,6 +420,10 @@ module Apiwork
         referenced_type.shape.key?(discriminator)
       end
 
+      def resolve_error_statuses(raises)
+        raises.map { |code| @export.api.error_codes[code].status }.uniq.sort
+      end
+
       def resolve_enum_schema(param)
         return nil unless param.scalar? && param.enum?
 

data/lib/apiwork/export.rb

@@ -74,6 +74,7 @@ module Apiwork
         register(OpenAPI)
         register(TypeScript)
         register(Zod)
+        register(Sorbus)
       end
     end
   end

data/lib/apiwork/introspection/action/request.rb

@@ -18,6 +18,14 @@ module Apiwork
           @dump = dump
         end
 
+        # @api public
+        # The description for this request.
+        #
+        # @return [String, nil]
+        def description
+          @dump[:description]
+        end
+
         # @api public
         # The query for this request.
         #
@@ -56,6 +64,7 @@ module Apiwork
         # @return [Hash]
         def to_h
           {
+            description:,
             body: body.transform_values(&:to_h),
             query: query.transform_values(&:to_h),
           }

data/lib/apiwork/introspection/action/response.rb

@@ -28,6 +28,14 @@ module Apiwork
           @body ||= @dump[:body] ? Param.build(@dump[:body]) : nil
         end
 
+        # @api public
+        # The description for this response.
+        #
+        # @return [String, nil]
+        def description
+          @dump[:description]
+        end
+
         # @api public
         # Whether this response has no content.
         #
@@ -49,7 +57,7 @@ module Apiwork
         #
         # @return [Hash]
         def to_h
-          { body: body&.to_h, no_content: no_content? }
+          { description:, body: body&.to_h, no_content: no_content? }
         end
       end
     end

data/lib/apiwork/introspection/dump/action.rb

@@ -23,7 +23,7 @@ module Apiwork
 
         private
 
-        def i18n_lookup(field)
+        def i18n_lookup(*segments)
           contract_class = @contract_action.contract_class
           return nil unless contract_class.name
 
@@ -32,15 +32,16 @@ module Apiwork
             contract_class.name.demodulize.delete_suffix('Contract').underscore,
             :actions,
             @contract_action.name,
-            field,
+            *segments,
           )
         end
 
         def build_request(request)
-          return { body: {}, query: {} } unless request
+          return { body: {}, description: i18n_lookup(:request, :description), query: {} } unless request
 
           {
             body: build_param(request.body),
+            description: request.description || i18n_lookup(:request, :description),
             query: build_param(request.query),
           }
         end
@@ -50,13 +51,14 @@ module Apiwork
         end
 
         def build_response(response)
-          return { body: {}, no_content: false } unless response
-          return { body: {}, no_content: true } if response.no_content?
+          return { body: {}, description: i18n_lookup(:response, :description), no_content: false } unless response
+          return { body: {}, description: response.description || i18n_lookup(:response, :description), no_content: true } if response.no_content?
 
+          description = response.description || i18n_lookup(:response, :description)
           body_shape = response.body
-          return { body: {}, no_content: false } unless body_shape
+          return { description:, body: {}, no_content: false } unless body_shape
 
-          { body: Param.new(body_shape, result_wrapper: response.result_wrapper).to_h, no_content: false }
+          { description:, body: Param.new(body_shape).to_h, no_content: false }
         end
 
         def raises

data/lib/apiwork/introspection/dump/param.rb

@@ -4,9 +4,8 @@ module Apiwork
   module Introspection
     module Dump
       class Param
-        def initialize(contract_param, result_wrapper: nil, visited: Set.new)
+        def initialize(contract_param, visited: Set.new)
           @contract_param = contract_param
-          @result_wrapper = result_wrapper
           @visited = visited
           @import_prefix_cache = {}
         end
@@ -14,8 +13,6 @@ module Apiwork
         def to_h
           return nil unless @contract_param
 
-          return build_result_wrapped if @result_wrapper
-
           result = {}
 
           @contract_param.params.sort_by { |name, _options| name.to_s }.each do |name, param_options|
@@ -31,38 +28,6 @@ module Apiwork
 
         private
 
-        def build_result_wrapped
-          success_type = @result_wrapper[:success_type]
-          error_type = @result_wrapper[:error_type]
-
-          success_variant = if success_type
-                              { reference: success_type, type: :reference }
-                            else
-                              { reference: nil, shape: build_success_params, type: :object }
-                            end
-
-          error_variant = if error_type
-                            { reference: error_type, type: :reference }
-                          else
-                            { reference: nil, shape: {}, type: :object }
-                          end
-
-          {
-            type: :union,
-            variants: [success_variant, error_variant],
-          }
-        end
-
-        def build_success_params
-          success_params = {}
-          @contract_param.params.sort_by { |name, _options| name.to_s }.each do |name, param_options|
-            dumped = build_param(name, param_options)
-            dumped[:optional] = true if param_options[:optional]
-            success_params[name] = dumped
-          end
-          success_params
-        end
-
         def build_param(name, options)
           return build_union_param(options) if options[:type] == :union
           return build_custom_type_param(options) if options[:custom_type]

data/lib/apiwork/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apiwork
-  VERSION = '0.1.2'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apiwork
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - skiftle
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-24 00:00:00.000000000 Z
+date: 2026-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -122,7 +122,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-description:
+description: Define your API once — and generate everything from it
 email:
 executables: []
 extensions: []
@@ -252,6 +252,8 @@ files:
 - lib/apiwork/export/pipeline.rb
 - lib/apiwork/export/pipeline/writer.rb
 - lib/apiwork/export/registry.rb
+- lib/apiwork/export/sorbus.rb
+- lib/apiwork/export/sorbus_mapper.rb
 - lib/apiwork/export/surface_resolver.rb
 - lib/apiwork/export/type_analysis.rb
 - lib/apiwork/export/type_script.rb
@@ -330,7 +332,9 @@ homepage: https://apiwork.dev
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/skiftle/apiwork/issues
   changelog_uri: https://github.com/skiftle/apiwork/blob/main/CHANGELOG.md
+  documentation_uri: https://apiwork.dev/guide/introduction
   homepage_uri: https://apiwork.dev
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/skiftle/apiwork
@@ -352,5 +356,5 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: The craft of API design
+summary: Typed APIs for Rails
 test_files: []