utoipa-ts

Why?

When making fullstack applications with Rust and TypeScript (e.g. with SvelteKit), you usually have to write type definitions on both ends. This can lead to types going out of sync and is also just really annoying to deal with.

This crate aims to solve that by automatically generating TypeScript types from your Rust API endpoint definitions.

What?

Rust crate that generates TypeScript types from utoipa API endpoint definitions. It extracts endpoint information for all defined endpoints and generates TypeScript bindings for them with the help of ts-rs.

Get started

Either add it as a dependency in your Cargo.toml:

[dependencies]
utoipa-ts = "0.1"

Or do it automatically with cargo add:

cargo add utoipa-ts

Already using utoipa?

To add utoipa-ts to an existing project that already uses utoipa, simply add the dependency, change all utoipa::path attributes to utoipa_ts::path, and add utoipa_ts::export!() to your codebase.

The types file can then be generated by running cargo test export_api.

Configuration

The export path for utoipa_ts::export!() can be chosen with utoipa_ts::export!("you/path/here.ts"). If a path is not present, it will use the default value of types.ts. The UTOIPA_TS_PATH environment variable can also be used to set the export path. If both are present, the environment variable will have priority.

Examples

use utoipa::ToSchema;

#[derive(ts_rs::TS, ToSchema)]
struct Todo {
    id: String,
    title: String,
    done: bool,
}

#[derive(ts_rs::TS, ToSchema)]
struct CreateTodo {
    title: String,
}

#[utoipa_ts::path(
    get,
    path = "/todos",
    responses(
        (status = 200, description = "List of all todos", body = Vec<Todo>),
    )
)]
async fn list_todos() {}

#[utoipa_ts::path(
    post,
    path = "/todos",
    request_body = CreateTodo,
    responses(
        (status = 201, description = "Todo created", body = Todo),
        (status = 400, description = "Invalid input")
    )
)]
async fn create_todo() {}

utoipa_ts::export!("types.ts");

fn main() {}

To generate the types.ts file, run the following command:

cargo test export_api

// This file was generated by utoipa-ts. Do not edit it manually.

export type CreateTodo = { title: string, };

export type Todo = { id: string, title: string, done: boolean, };

export type Api = {
  "GET /todos": {
    responses: {
      200: Array<Todo>;
    };
  };
  "POST /todos": {
    body: CreateTodo;
    responses: {
      201: Todo;
      400: never;
    };
  };
};

Disclaimer

This project is not affiliated with utoipa.