Custom Exports

Custom exports extend Apiwork with additional output formats.

Creating a Custom Export

class MyExport < Apiwork::Export::Base
  export_name :my_export
  output :hash

  def generate
    # Build and return the export
    {
      resources: build_resources,
      types: build_types
    }
  end

  private

  def build_resources
    result = {}
    api.resources.each do |name, resource|
      result[name] = process_resource(resource)
    end
    result
  end

  def build_types
    api.types.transform_values { |t| process_type(t) }
  end
end

Output Type

Set the output type for the export:

output :hash    # Returns a Hash — serialized to JSON or YAML by the framework
output :string  # Returns a String — written as-is (use for TypeScript, Zod, etc.)

For :hash exports, the framework handles serialization to JSON or YAML based on the requested format. For :string exports, set file_extension to control the file type (e.g., .ts).

Base Class Helpers

The Apiwork::Export::Base class provides:

API Access

api            # Full introspection data (Introspection::API)
api.types      # All registered types
api.enums      # All registered enums
api.info       # API metadata (title, version, etc.)
api_base_path  # API mount path
options        # Resolved options

The api object contains the full introspection output. For details on the format, field types, and properties, see Introspection.

Iteration

api.resources.each_value do |resource|
  resource.actions.each_value do |action|
    # Called for each action in a resource
  end
end

Options

option :my_option, type: :string, default: 'value'

# Access in generate:
my_option  # Returns the configured value

Registration

Custom exports are registered so Apiwork can find them:

# config/initializers/apiwork.rb
Apiwork::Export.register(MyExport)

Usage

Once registered, enable it in the API definition:

Apiwork::API.define '/api/v1' do
  export :my_export
end

With options:

Apiwork::API.define '/api/v1' do
  export :my_export do
    key_format :camel
  end
end

Served at GET /api/v1/.my_export.

With query parameters (any defined option works):

GET /api/v1/.my_export?key_format=camel
GET /api/v1/.my_export?locale=sv
GET /api/v1/.my_export?include_deprecated=true

Generate to file (use uppercase ENV vars):

rake apiwork:export:write EXPORT_NAME=my_export OUTPUT=public/exports
rake apiwork:export:write EXPORT_NAME=my_export KEY_FORMAT=camel OUTPUT=public/exports
rake apiwork:export:write EXPORT_NAME=my_export INCLUDE_DEPRECATED=true OUTPUT=public/exports

Defining Options

Exports are configurable with option:

class MyExport < Apiwork::Export::Base
  export_name :my_export

  option :include_deprecated, type: :boolean, default: false
  option :max_depth, type: :integer, default: 3
end

TIP

key_format and locale are always available and do not need to be defined. They are inherited from the API definition and can be overridden via query parameters or ENV vars.

Option Types

Type	Description
:string	String value
:integer	Integer value
:symbol	Symbol value
:boolean	Boolean value
:hash	Nested options (use block)

Accessing Options

Options are available as methods in the generate method:

def generate
  return {} unless include_deprecated || has_content?
  # ...
end