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.

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
• Supports OpenApi 3.0/3.1 Schema

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

Prerequisites

• .NET 10.0 SDK
• Node.js (for consuming generated TypeScript clients)
• 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:

make test

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 OpenApiGen/OpenApiGen.csproj -- --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 OpenApiGen/OpenApiGen.csproj -- --transport axios Examples/PetStore.json ./generated

dotnet run --project OpenApiGen/OpenApiGen.csproj -- --transport fetch Examples/PetStore.json ./generated

Project Structure

• OpenApiGen/ - Main C# generator code
• Examples/ - Example OpenAPI definitions and configuration files

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.