Fetch Frog

Type safe api clients using OpenApi Specs

Framework Integrations

• Nuxt - SSR-ready reactive fetching with useFetch integration
• Svelte - Svelte and SvelteKit optimized implementation (coming soon)

Usage

Single schema

pnpm fetch-frog generate schema.yaml -o schema.d.ts

# schema.yaml -> schema.ts

Supports both json, yml, urls and local file paths

For the full list of options, see openapi-ts.pages.dev/cli

Using the fetch client

// src/lib/apiClient.ts
import { createFetchClient } from "fetch-frog";
import type { paths } from "$lib/types/api/v1"; // generated api types

export const apiClient = createFetchClient<paths>(
	"https://petstore3.swagger.io/api/v3",
	{}
);

// src/lib/index.ts
import { apiClient } from "$lib/apiClient";

const { data } = await apiClient("/pet/{petId}", {
	path: {
		petId: "frog",
	},
});

console.log(data);

This uses ofetch under the hood.

Handling formdata

Fetch Frog provides a formdataBodySerializer util function to convert flat objects into formdata while keeping the object type.

import { apiClient } from "$lib/apiClient";
import { formdataBodySerializer } from "fetch-frog";

const { data } = await apiClient("/pet/{petId}/uploadImage", {
	path: {
		petId: "frog",
	},
	method: "POST",
	body: formdataBodySerializer({
		additionalMetadata: "string",
		file: new File([""], "frog.png", { type: "image/png" }),
	}),
});

import { apiClient } from "$lib/apiClient";
import { formdataBodySerializer } from "fetch-frog";

const { data } = await apiClient("/auth/login", {
	method: "POST",
	body: formdataBodySerializer({
		username: "string",
		password: "string",
	}),
});

Automatic FormData conversion

Fetch Frog provides a containsFileOrBlob utility that can detect when your request body contains File or Blob objects, enabling automatic conversion to FormData.

import { containsFileOrBlob, formdataBodySerializer } from "fetch-frog";

const requestBody = {
	name: "Profile picture",
	file: new File([""], "avatar.jpg", { type: "image/jpeg" }),
	metadata: "user avatar",
};

// Check if the body contains files/blobs
if (containsFileOrBlob(requestBody)) {
	const { data } = await apiClient("/user/avatar", {
		method: "POST",
		body: formdataBodySerializer(requestBody), // convert to FormData while preserving type
	});
}

Note

If you're using a framework like Nuxt or Svelte, consider using the framework-specific implementations of containsFileOrBlob and formdataBodySerializer. See Framework Integrations for more details.

Examples

An example for creating a reusable wrapper composable, useful for authentication headers for example, can be found in examples/composable-wrapper

Storing the body / path- or query parameters / response with types requires extracting a type from the generated openapi ts definitions. Some type helpers are exposed from fetch-frog to help with this: ExtractResponse, ExtractBody, ExtractQueryParams, ExtractPathParams where QueryParams and PathParams are reactive to help with UseFetch. For example usage, see examples/type-extraction-helpers

Cli tools

Convert schema version

Convert a schema from 1.x or 2.x to 3.0.1 using swagger2openapi

fetch-frog convert v2.schema.yaml -o v3.schema.json

Generate

Generate types from a schema, uses openapi-ts.pages.dev/cli under the hood

fetch-frog generate v3.schema.json -o schema.d.ts

Credits

• openapi-ts
• enkot/nuxt-open-fetch