apiwork 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef169b6db5b913f078945dbf9b29939139cd80d5d77e07c0339e9df070dfb259
-  data.tar.gz: b979dc9b7b721f5949952a22572fa8ea99593f59f1c5161a91fc8757b28205d5
+  metadata.gz: eb5f681a0f08e4bebe2d0f5ebf4edac733f3787e4144f019bc4babfa7a7ef84a
+  data.tar.gz: e5d1d87115d2902295d66567c324d73ef15d01b0ac106c1fa9739b56a276aeb3
 SHA512:
-  metadata.gz: 46548e8a016ade99fecc507ac9cb7d575b21278d4981e2ea5ebed9ddbdb81b2ff270669c4acca0f0cd6ce5e7437c9b14f62d51eff650492160e136f950a040fe
-  data.tar.gz: 8aabaa2bd3d750d425429ba4f47d034a07c1562c3ca5f90405d2c1d17e1f159d499e64bd906667bf9f6fe7dd3ee0640863dcb797a264ba985fcee6753f74925b
+  metadata.gz: bb539d87fcd3b065d643711616f7f9f5589d574cbf12bcc06c69aafe7000f6fafa4e19d7fd34cd165d2734076d3b192472a6f51459074241fabbf5dd3faece42
+  data.tar.gz: 692745d73d86c3f5c377ae2a7962b38efe351b1fc893df6af45bd8de025622f61257307dedcd1b6aac15df8f3112874e92c54d3b3e316ef9aaa59ef6fcca0338

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
@@ -270,13 +268,9 @@ module Apiwork
         else
           build_custom_action_response(contract_class, representation_class, action, contract_action)
         end
-
-        build_request_query_type(contract_class, action.name, contract_action)
-        build_request_body_type(contract_class, action.name, contract_action)
       end
 
       def build_member_action_response(contract_class, representation_class, action, contract_action)
-        build_response_body_type(contract_class, representation_class, action.name, :member)
         member_shape_class = self.class.member_wrapper.shape_class
         data_type = resolve_resource_data_type(representation_class)
 
@@ -288,7 +282,6 @@ module Apiwork
       end
 
       def build_collection_action_response(contract_class, representation_class, action, contract_action)
-        build_response_body_type(contract_class, representation_class, action.name, :collection)
         collection_shape_class = self.class.collection_wrapper.shape_class
         data_type = resolve_resource_data_type(representation_class)
 
@@ -309,70 +302,10 @@ module Apiwork
         end
       end
 
-      def build_response_body_type(contract_class, representation_class, action_name, response_type)
-        type_name = [action_name, 'response_body'].join('_').to_sym
-        return if contract_class.type?(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(type_name) do |object|
-          shape_class.apply(object, representation_class.root_key, capabilities, representation_class, response_type, data_type:)
-        end
-      end
-
-      def build_request_query_type(contract_class, action_name, contract_action)
-        request = contract_action.request
-        return unless request.query.params.any?
-
-        type_name = [action_name, 'request_query'].join('_').to_sym
-        return if contract_class.type?(type_name)
-
-        contract_class.object(type_name) do |object|
-          request.query.params.each { |name, param| object.param(name, **normalize_request_param(param)) }
-        end
-      end
-
-      def build_request_body_type(contract_class, action_name, contract_action)
-        request = contract_action.request
-        return unless request.body.params.any?
-
-        type_name = [action_name, 'request_body'].join('_').to_sym
-        return if contract_class.type?(type_name)
-
-        contract_class.object(type_name) do |object|
-          request.body.params.each { |name, param| object.param(name, **normalize_request_param(param)) }
-        end
-      end
-
-      def normalize_request_param(param)
-        options = param.except(:name, :custom_type, :union, :partial)
-        options[:type] = param[:custom_type] if param[:custom_type]
-        options[:shape] = param[:union] if param[:union]
-        options
-      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

@@ -15,9 +15,31 @@ module Apiwork
           @contract_class = contract_class
           @action_name = action_name
           @body = 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,8 +204,10 @@ 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
           responses[:'200'] = {
             content: {
@@ -209,7 +215,7 @@ module Apiwork
                 schema: map_param(response.body),
               },
             },
-            description: 'Successful response',
+            description: response_description,
           }
 
           raises.each do |code|
@@ -228,10 +234,10 @@ module Apiwork
                 },
               },
             },
-            description: 'Successful response',
+            description: response_description,
           }
         else
-          responses[:'204'] = { description: 'No content' }
+          responses[:'204'] = { description: '' }
         end
 
         responses

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
@@ -131,7 +132,7 @@ module Apiwork
         if error_statuses.empty?
           "export type #{type_name} = #{success_variant};"
         else
-          error_variants = error_statuses.map { |status| "{ status: #{status}; body: #{pascal_case(:error_response_body)} }" }
+          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
@@ -258,27 +259,29 @@ module Apiwork
         end
       end
 
-      private
+      def build_action_types
+        types = []
 
-      def resolve_error_statuses(raises)
-        raises.map { |code| @export.api.error_codes[code].status }.uniq.sort
-      end
+        traverse_resources do |resource|
+          resource_name = resource.identifier.to_sym
+          parent_identifiers = resource.parent_identifiers
 
-      def build_enum_types(surface)
-        surface.enums.map do |name, enum|
-          { code: build_enum_type(name, enum), name: pascal_case(name) }
-        end
-      end
+          resource.actions.each do |action_name, action|
+            types.concat(build_request_types(resource_name, action_name, action.request, 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) }
+            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|
@@ -286,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, 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?)
@@ -317,30 +348,6 @@ module Apiwork
         types
       end
 
-      def build_response_types(resource_name, action_name, action, parent_identifiers:)
-        types = []
-        response = action.response
-
-        if 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
-
-        type_name = action_type_name(resource_name, action_name, 'Response', parent_identifiers:)
-        code = build_action_response_type(resource_name, action_name, response, parent_identifiers:, raises: action.raises)
-        types << { code:, name: type_name }
-
-        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
 
@@ -169,7 +171,7 @@ module Apiwork
           "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_response_body)}Schema })"
+            "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]);"
@@ -315,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?
@@ -377,8 +377,21 @@ module Apiwork
 
             response = action.response
             schemas << build_action_response_body_schema(resource_name, action_name, response.body, parent_identifiers:) if response.body?
+          end
+        end
 
-            schemas << build_action_response_schema(resource_name, action_name, response, parent_identifiers:, raises: action.raises)
+        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
 
@@ -392,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

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).to_h, no_content: false }
+          { description:, body: Param.new(body_shape).to_h, no_content: false }
         end
 
         def raises

data/lib/apiwork/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apiwork
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - skiftle
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-26 00:00:00.000000000 Z
+date: 2026-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -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