TypeSpec From Serializers

Automatically generate TypeSpec descriptions from your JSON serializers.

Currently, this library targets oj_serializers and ActiveRecord in Rails applications.

Why? 🤔

It's easy for the backend and the frontend to become out of sync. Traditionally, preventing bugs requires writing extensive integration tests.

TypeSpec is a great tool to catch this kind of bugs and mistakes, as it can define precise API specifications and detect mismatches, but writing these specifications manually is cumbersome, and they can become stale over time, giving a false sense of confidence.

This library takes advantage of the declarative nature of serializer libraries such as active_model_serializers and oj_serializers, extending them to allow embedding type information, as well as inferring types from the SQL schema when available.

The project builds on types_from_serializers by ElMassimo, originally designed for TypeScript definitions, adapting it to generate TypeSpec specifications instead. This shift broadens interoperability with modern API specification tools and leverages TypeSpec’s strengths in defining RESTful APIs, including route generation from Rails applications, to create comprehensive, type-safe API descriptions.

As a result, it's possible to easily detect mismatches between the backend and the frontend, as well as make the fields and endpoints more discoverable and provide great autocompletion in tools that support TypeSpec, without having to manually write the specifications.

Features ⚡️

• Start simple, no additional syntax required
• Infers types from a related ActiveRecord model, using the SQL schema
• Understands TypeSpec native types and how to map SQL columns: string, boolean, etc
• Automatically types associations, importing the generated types for the referenced serializers
• Detects conditional attributes and marks them as optional: name?: string
• Fallback to a custom interface using typespec_from
• Supports custom types and automatically adds the necessary imports
• Generates TypeSpec route interfaces from Rails routes, mapping controllers and actions to HTTP operations

Demo 🎬

For a database schema like this one:

DB Schema

  create_table "composers", force: :cascade do |t|
    t.text "first_name"
    t.text "last_name"
    t.datetime "created_at", precision: 6, null: false
    t.datetime "updated_at", precision: 6, null: false
  end

  create_table "songs", force: :cascade do |t|
    t.text "title"
    t.integer "composer_id"
    t.datetime "created_at", precision: 6, null: false
    t.datetime "updated_at", precision: 6, null: false
  end

  create_table "video_clips", force: :cascade do |t|
    t.text "title"
    t.text "youtube_id"
    t.integer "song_id"
    t.integer "composer_id"
    t.datetime "created_at", precision: 6, null: false
    t.datetime "updated_at", precision: 6, null: false
  end

and a serializer like this:

class VideoSerializer < BaseSerializer
  object_as :video, model: :VideoClip

  attributes :id, :created_at, :title, :youtube_id

  type :string, optional: true
  def youtube_url
    "https://www.youtube.com/watch?v=#{video.youtube_id}" if video.youtube_id
  end

  has_one :song, serializer: SongSerializer
end

this fork generates a TypeSpec model like:

import "./Song.tsp";

model Video {
  id: int32;
  createdAt: utcDateTime;
  title?: string;
  youtubeId?: string;
  youtubeUrl?: string;
  song: Song;
}

Note

This reflects the default setup for TypeSpec generation. You can customize everything—check out the configuration options for full control!

Installation 💿

Add this line to your application's Gemfile:

gem 'typespec_from_serializers'

And then run:

$ bundle install

Usage 🚀

To get started, create a BaseSerializer that extends Oj::Serializer, and include the TypeSpecFromSerializers::DSL module.

# app/serializers/base_serializer.rb

class BaseSerializer < Oj::Serializer
  include TypeSpecFromSerializers::DSL
end

Note

You can customize this behavior using base_serializers.

Warning

All serializers should extend one of the base_serializers, or they won't be detected.

SQL Attributes

In most cases, you'll want to let TypeSpecFromSerializers infer the types from the SQL schema.

If you are using ActiveRecord, the model related to the serializer will be inferred can be inferred from the serializer name:

UserSerializer => User

It can also be inferred from an object alias if provided:

class PersonSerializer < BaseSerializer
  object_as :user

In cases where we want to use a different alias, you can provide the model name explicitly:

class PersonSerializer < BaseSerializer
  object_as :person, model: :User

Model Attributes

When you want to be more strict than the SQL schema, or for attributes that are methods in the model, you can use:

  attributes(
    name: {type: :string},
    status: {type: :Status}, # a custom type in ~/typespec/Status.tsp
  )

Serializer Attributes

For attributes defined in the serializer, use the type helper:

  type :boolean
  def suspended
    user.status.suspended?
  end

Note

When specifying a type, attribute will be called automatically.

Fallback Attributes

You can also specify typespec_from to provide a TypeSpec model that should be used to obtain the field types:

class LocationSerializer < BaseSerializer
  object_as :location, typespec_from: :GoogleMapsLocation

  attributes(
    :lat,
    :lng,
  )
end

import "./typespec/GoogleMapsLocation.tsp";

model Location {
  lat: GoogleMapsLocation.lat::type;
  lng: GoogleMapsLocation.lng::type;
}

Generation 📜

To get started, run bin/rails s to start the Rails development server.

TypeSpecFromSerializers will automatically register a Rails reloader, which detects changes to serializer files, and will generate code on-demand only for the modified files.

It can also detect when new serializer files are added, or removed, and update the generated code accordingly.

Manually

To generate types manually, use the rake task:

bundle exec rake typespec_from_serializers:generate

or if you prefer to do it manually from the console:

require "typespec_from_serializers/generator"

TypeSpecFromSerializers.generate(force: true)

With vite-plugin-full-reload ⚡️

When using Vite Ruby, you can add vite-plugin-full-reload to automatically reload the page when modifying serializers, causing the Rails reload process to be triggered, which is when generation occurs.

// vite.config.tsp
import { defineConfig } from 'vite'
import ruby from 'vite-plugin-ruby'
import reloadOnChange from 'vite-plugin-full-reload'

defineConfig({
  plugins: [
    ruby(),
    reloadOnChange(['app/serializers/**/*.rb'], { delay: 200 }),
  ],
})

As a result, when modifying a serializer and hitting save, the type for that serializer will be updated instantly!

Routes Generation 🛤️

In addition to generating TypeSpec models from serializers, TypeSpecFromSerializers can generate a routes.tsp file based on your Rails application's routes. This feature creates TypeSpec interfaces for your API endpoints, mapping Rails controllers and actions to HTTP operations.

For example, given Rails routes like:

Rails.application.routes.draw do
  resources :videos, only: [:index, :show]
end

The generator produces a routes.tsp file like:

import "@typespec/http";

import "./models/Videos.tsp";

using TypeSpec.Http;

namespace Routes {
  @route("/videos")
  interface Videos {
    @get list(): Videos[];
    @get read(@path id: string): Videos;
  }
}

Configuration ⚙️

You can configure generation in a Rails initializer:

# config/initializers/typespec_from_serializers.rb

if Rails.env.development?
  TypeSpecFromSerializers.config do |config|
    config.name_from_serializer = ->(name) { name }
  end
end

namespace

Default: nil

Allows to specify a TypeSpec namespace and generate .tsp to make types available globally, avoiding the need to import types explicitly.

base_serializers

Default: ["BaseSerializer"]

Allows you to specify the base serializers, that are used to detect other serializers in the app that you would like to generate interfaces for.

serializers_dirs

Default: ["app/serializers"]

The dirs where the serializer files are located.

output_dir

Default: "app/frontend/typespec/generated"

The dir where the generated TypeSpec interface files are placed.

custom_typespec_dir

Default: "app/frontend/types"

The dir where the custom types are placed.

name_from_serializer

Default: ->(name) { name.delete_suffix("Serializer") }

A Proc that specifies how to convert the name of the serializer into the name of the generated TypeSpec interface.

global_types

Default: ["Array", "Record", "Date"]

Types that don't need to be imported in TypeSpec.

You can extend this list as needed if you are using global definitions.

skip_serializer_if

Default: ->(serializer) { false }

You can provide a proc to avoid generating serializers.

Along with base_serializers, this provides more fine-grained control in cases where a single backend supports several frontends, allowing to generate types separately.

sql_to_typespec_type_mapping

Specifies how to map SQL column types to TypeSpec native and custom types.

# Example: You have response middleware that automatically converts date strings
# into Date objects, and you want TypeSpec to treat those fields as `plainDate`.
config.sql_to_typespec_type_mapping.update(
  date: :plainDate,
  datetime: :utcDateTime,
)

# Example: You won't transform fields when receiving data in the frontend
# (date fields are serialized to JSON as strings).
config.sql_to_typespec_type_mapping.update(
  date: :string,
  datetime: :utcDateTime,
)

transform_keys

Default: ->(key) { key.camelize(:lower).chomp("?") }

You can provide a proc to transform property names.

This library assumes that you will transform the casing client-side, but you can generate types preserving case by using config.transform_keys = ->(key) { key }.

Contact ✉️

Please use Issues to report bugs you find, and Discussions to make feature requests or get help.

Don't hesitate to ⭐️ star the project if you find it useful!

Using it in production? Always love to hear about it! 😃

License

The gem is available as open source under the terms of the MIT License.