Skip to content

About

TypeScript OpenApi Generator

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

OpenApiGen

OpenApiGen is a .NET tool for generating OpenAPI-based TypeScript clients. It aims to produce simple, type-safe, and easily consumable clients for modern TypeScript applications, especially those using React Query with Axios or fetch.

Build Status

NuGet Version

Changelog

Why OpenApiGen?

Existing tools often generate overly complicated clients. OpenApiGen focuses on:

  • Obvious input/output messages: 1 input message + query args, 1 output message. Everything inlined unless specified.
  • Simple functions for each operation: Easy integration with React Query, no complicated classes or inheritance trees.

Example Generated Output

Below is a sample of the TypeScript client code generated by OpenApiGen for a PATCH operation on /User/{id} using the Axios transport. This output demonstrates the inlined request/response types and the simple function signature designed for easy integration with tools like React Query:

// === patch /User/{id} ===
export type UserIdPatchRequest = {
    firstName: null | string
    lastName: null | string
}
export type UserIdPatch200Response = {
    firstName: string
    lastName: string
}
export type UserIdPatch400Response = ProblemDetails
export type UserIdPatch404Response = ProblemDetails
export async function patchUserId(axios: AxiosInstance, bearer: string, id: string, request: UserIdPatchRequest): Promise<[200, UserIdPatch200Response] | [400, UserIdPatch400Response] | [404, UserIdPatch404Response]> {
    const __queryString__ = "";
    const __headers__: Record<string, string> = {};
    __headers__.Authorization = `Bearer ${bearer}`;
    __headers__["Content-Type"] = "application/json";
    const __response__ = await axios.request({
        method: "PATCH",
        url: `/User/${id}${__queryString__}`,
        data: JSON.stringify(request),
        headers: __headers__,
        validateStatus: () => true,
    });
    switch (__response__.status) {
        case 200: return [200, __response__.data as UserIdPatch200Response]
        case 400: return [400, __response__.data as UserIdPatch400Response]
        case 404: return [404, __response__.data as UserIdPatch404Response]
        default: throw Error(`Unexpected status ${__response__.status}`)
    }
}

Features

  • Generates TypeScript clients from OpenAPI definitions
  • Supports Axios and fetch transports
  • Designed for easy integration with React Query
  • Inlines types for clarity and simplicity
  • Support for Bearer token (authorization header) and ApiKey (cookie)
  • Minimal dependencies, no runtime bloat
  • Accepts OpenAPI 3.0, 3.1, and 3.2 JSON for supported HTTP operations and payloads, including OpenAPI 3.2 QUERY

Getting Started

Install via .NET Tool

You can install the latest released binary globally using the .NET CLI:

dotnet tool install --global MagnusOpera.OpenApiGen

Or update to the latest version:

dotnet tool update --global MagnusOpera.OpenApiGen

After installation, you can run the tool using:

openapigen --help

The tool package includes .NET 10 and .NET 11 targets. Install it with the SDK for the runtime you use. A project can also install it with dotnet tool install --local MagnusOpera.OpenApiGen from a directory with a tool manifest, then invoke it with dotnet tool run openapigen.

Prerequisites

  • .NET 11 SDK to build and pack both tool targets
  • .NET 10 SDK alongside .NET 11 and Node.js 24 for the full regression suite
  • GNU Make (optional, for building with make)

Build

Clone the repository and build the tool:

git clone https://github.com/MagnusOpera/OpenApiGen.git
cd OpenApiGen
make build

Test

Run the regression tests:

npm ci
make test config=Release

The suite builds the sample API on both frameworks and checks the resulting OpenAPI 3.1 and 3.2 documents against the client snapshots. It also installs the same NuGet tool package with both SDKs, generates Axios and fetch clients from both documents, type-checks them, and exercises their request and response handling.

To run the generator with the provided sample project:

make gen transport=axios
make gen transport=fetch

This will generate a TypeScript client from the sample API definition in Examples/SampleApi.json. Output is available in the generated folder.

Usage

Run the generator with your OpenAPI definition:

dotnet run --project src/OpenApiGen/OpenApiGen.csproj -f net10.0 -- --transport <axios|fetch> <path-to-openapi.json> <output-dir>

With:

  • --transport <axios|fetch>: mandatory transport to generate
  • <path-to-openapi.json>: path to openapi definition file
  • : path to generated client. WARNING: content is purged without notice.

Transport Selection

Use --transport axios to generate clients whose first argument is an AxiosInstance:

export async function getPets(axios: AxiosInstance, limit?: number): Promise<[200, PetsGet200Response] | [0, PetsGet0Response]>

Use --transport fetch to generate clients whose first argument is a fetch implementation:

export async function getPets(fetcher: typeof fetch, limit?: number): Promise<[200, PetsGet200Response] | [0, PetsGet0Response]>

The fetch transport keeps the runtime dependency surface minimal and works with any injected fetch implementation available in your environment.

Example

dotnet run --project src/OpenApiGen/OpenApiGen.csproj -f net10.0 -- --transport axios Examples/PetStore.json ./generated
dotnet run --project src/OpenApiGen/OpenApiGen.csproj -f net11.0 -- --transport fetch Examples/PetStore.json ./generated

Project Structure

  • src/OpenApiGen/ contains the .NET tool.
  • src/SampleApi/ contains the ASP.NET Core sample.
  • src/OpenApiGen.Tests/ contains the regression suite.
  • Examples/ contains sample OpenAPI documents.
  • website/public/ contains the product site and documentation.

With Node.js installed, run make website and open http://localhost:8000 to preview the site locally.

To publish, set Settings → Pages → Source to GitHub Actions. Once the site changes are on main, run the Publish Website workflow from the Actions tab.

Contributing

Contributions are welcome! Please open issues or pull requests for bug fixes, features, or documentation improvements.

License

This project is licensed under the MIT License. See LICENSE.md for details.

About

TypeScript OpenApi Generator

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages