OpenApiTsGen 0.1.2

OpenApiTsGen

OpenApiTsGen reads an OpenAPI JSON document exposed by an ASP.NET Core application and writes a typed TypeScript client (apiserver.ts) plus model declarations (models.ts). It preserves required/optional and nullable schema metadata, path/query/header parameters, JSON bodies, multipart forms, and binary uploads.

Install

dotnet add package OpenApiTsGen

The package targets .NET 8 and can be consumed by ASP.NET Core 8 or newer applications.

Configure ASP.NET Core

First expose an OpenAPI document (Swagger is used here only as an example):

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddTsApiGen(builder.Configuration);

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.TsApiGen();
}

Add the following configuration to appsettings.Development.json:

{
  "TsApiGen": {
    "OpenApiUrl": "/swagger/v1/swagger.json",
    "OutputDir": "ClientApp/src/api",
    "Route": "/tools/ts-api-gen",
    "ApiFileName": "apiserver.ts",
    "ModelsFileName": "models.ts"
  }
}

Run the API and call GET /tools/ts-api-gen. Relative output paths are resolved from the ASP.NET Core content root. Relative OpenAPI URLs are resolved on the same host as the generation request. When calling OpenApiTypeScriptApiGenerator.GenerateAsync() directly (for example from a build tool), configure an absolute OpenApiUrl.

You may configure the generator without an IConfiguration section:

builder.Services.AddTsApiGen(options =>
{
    options.OpenApiUrl = "https://localhost:7001/swagger/v1/swagger.json";
    options.OutputDir = "ClientApp/src/api";
});

Keep the generation endpoint development-only or protect it with authorization: it makes an HTTP request and writes files on the server. Do not expose it publicly in production.

OpenAPI contract guidelines

The input must be an OpenAPI 3.x JSON document. For stable and useful generated contracts:

• Give every operation a unique, stable operationId; it becomes the TypeScript method name. Without one, the name is derived from the HTTP method and route.
• Put reusable DTOs under components.schemas and use $ref. Mark non-optional properties in the schema's required array and express nullability explicitly (nullable: true in OpenAPI 3.0, or a null union in OpenAPI 3.1).
• Declare contract-critical headers as explicit header parameters. Do not rely on prose descriptions for required inputs.
• Keep route groups and tags consistent, and use distinct operationId values across the entire API.
• Describe path, query, and header parameters with their correct in and required values. OpenAPI requires path parameters to be required.
• Use application/json for JSON request bodies and multipart/form-data with type: string, format: binary for file fields.
• Avoid renaming schemas, properties, routes, or operationId values after publishing a client; those are client contract changes.

Complete integration guides with stable operation names, nullable fields, JSON bodies, and file upload metadata are available for both application styles:

• ASP.NET Core Minimal API
• ASP.NET Core MVC controllers

Generated client usage

The generated API module uses Axios. Install it in the consuming frontend:

npm install axios

Pass contract headers through the generated method argument when the OpenAPI document declares them as parameters. Cross-cutting headers such as authorization can also be supplied through the generated request config.

Generated files should normally be regenerated from a committed OpenAPI contract and reviewed like source changes. In CI, compare regenerated output with the committed files to detect server/client drift.

License

OpenApiTsGen is licensed under the MIT License.