Taro - Typed Api using Ruby Objects

class BikesController < ApplicationController
  # This adds an endpoint summary, description, and tags to the docs (all optional)
  api     'Update a bike', desc: 'My longer text', tags: ['Bikes']
  # Params can come from the path, e.g. /bike/:id)
  param   :id, type: 'UUID', null: false, desc: 'ID of the bike to update'
  # They can also come from the query string or request body
  param   :bike, type: 'BikeInputType', null: false
  # Return types can differ by status code and can be nested as in this case:
  returns :bike, code: :ok, type: 'BikeType', desc: 'update success'
  # This one is not nested:
  returns code: :unprocessable_content, type: 'MyErrorType', desc: 'failure'
  def update
    # defined params are available as @api_params
    bike = Bike.find(@api_params[:id])
    success = bike.update(@api_params[:bike])

    # Types can be used to render responses.
    # The object
    if success
      render json: { bike: BikeType.render(bike) }, status: :ok
    else
      render json: MyErrorType.render(bike.errors.first), status: :unprocessable_entity
    end
  end

  # Support for arrays and paginated lists is built-in.
  api     'List all bikes'
  returns code: :ok, array_of: 'BikeType', desc: 'list of bikes'
  def index
    render json: BikeType.array.render(Bike.all)
  end
end

class BikeType < ObjectType
  # Optional description of BikeType (for API docs and the OpenAPI export)
  self.desc = 'A bike and all relevant information about it'

  # Object types have fields. Each field has a name, its own type,
  # and a `null:` setting to indicate if it can be nil.
  # Providing a desc is optional.
  field :brand, type: 'String', null: true, desc: 'The brand name'

  # Fields can reference other types and arrays of values
  field :users, array_of: 'UserType', null: false

  # Pagination is built-in for big lists
  field :parts, page_of: 'PartType', null: false

  # Custom methods can be chosen to resolve fields
  field :has_brand, type: 'Boolean', null: false, method: :brand?

  # Field resolvers can also be implemented or overridden on the type.
  # The object passed in to `BikeType.render` is available as `object`.
  field :fancy_info, type: 'String', null: false
  def fancy_info
    "A bike named #{object.name} with #{object.parts.count} parts."
  end
end

class BikeInputType < InputType
  field :brand,  type: 'String',  null: true,  desc: 'The brand name'
  field :wheels, type: 'Integer', null: false, default: 2
end

Taro.config.parse_params = false

Taro.config.validate_responses = false

class SeverityEnumType < EnumType
  value 'info'
  value 'warning'
  value 'debacle'
end

class ErrorType < ObjectType
  field :severity, type: 'SeverityEnumType', null: false
end

class ErrorType < ObjectType
  field :severity, type: 'String', enum: %w[info warning debacle], null: false
end

class ApiBaseController < ApplicationController
  def self.api(...)
    super
    returns code: :not_found, type: 'MyErrorType', desc: 'The record was not found'
  end

  rescue_from ActiveRecord::RecordNotFound, with: :render_not_found

  def render_not_found
    render json: MyErrorType.render(something), status: :not_found
  end
end

class AuthenticatedApiController < ApiBaseController
  def self.api(...)
    super
    returns code: :unauthorized, type: 'MyErrorType'
  end
  # ... rescue_from ... render ...
end

class BikeType < ObjectType
  field :secret_name, type: 'String', null: true

  def secret_name
    Current.user.superuser? ? object.secret_name : nil
  end
end

# config/initializers/taro.rb
%i[api param returns].each do |m|
  Taro::Rails::DSL.alias_method("taro_#{m}", m) # `taro_api` etc.
  Taro::Rails::DSL.define_method(m) { |*a, **k, &b| super(*a, **k, &b) }
end

module BikeUpdateDesc
  extend ActiveSupport::Concern

  included do
    api 'Update a bike', description: 'Long description', tags: ['Bikes']
    # lots of params and returns ...
  end
end

class BikesController < ApplicationController
  include BikeUpdateDesc
  def update # ...
end

# Implement ::derive_from in your custom type.
class PreviewType < Taro::Types::Scalar::StringType
  singleton_class.attr_reader :type_to_preview

  def self.derive_from(other_type)
    self.type_to_preview = other_type
  end

  def coerce_response
    type_to_preview.new(object).coerce_response.to_s.truncate(100)
  end
end

# Make it available in the DSL, e.g. in an initializer.
Taro::Types::BaseType.define_derived_type :preview, 'PreviewType'

# Usage:
class MyController < ApplicationController
  returns code: :ok, preview_of: 'BikeType'
  def show
    render json: BikeType.preview.render(Bike.find(params[:id]))
  end
end