# Generate a Typed API Client from an ASP.NET Core Swagger Document

Yes. An agent starts your ASP.NET Core API, reads the Swagger document it serves, generates a typed TypeScript client, tests it on the live server and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/generate-api-clients/aspnet-core/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the document is produced before it fetches it. In an ASP.NET Core API like realworld-apps/aspnetcore-realworld-example-app, `src/Conduit/Program.cs` calls `AddSwaggerGen` with a `Bearer` security definition (an `ApiKey` scheme in the `Authorization` header, `BearerFormat` JWT), one document named `v1` titled `RealWorld API`, `CustomSchemaIds` set to the type's full name with `+` turned into `.`, actions tagged by `GroupName`, and `UseSwagger` with the route template `swagger/{documentName}/swagger.json`, so the document is at `/swagger/v1/swagger.json`. Two conventions in `src/Conduit/Infrastructure` shape every path: `ApiRoutePrefixConvention` roots each controller under `api`, or whatever the `ApiPrefix` setting says, and `GroupByApiRootConvention` names each group after the first segment of the controller's route. `AddJsonOptions` sets `DefaultIgnoreCondition` to `Never`, so nullable fields such as `bio` and `image` serialize as explicit `null`, which the generated types must allow.

Then it reads the controllers the document describes. `Features/Articles/ArticlesController.cs` has `GET articles` with `tag`, `author`, `favorited`, `limit` and `offset` query parameters returning `ArticlesEnvelope` (`Articles` plus `ArticlesCount`), `GET articles/feed` behind `[Authorize]`, `GET articles/{slug}` returning `ArticleEnvelope`, and `POST`, `PUT` and `DELETE` with their status codes; `Features/Users/UsersController.cs` has `POST users` and `POST users/login`, both returning `UserEnvelope` with the `token`. One detail matters for a client that signs in: the integration tests in `tests/Conduit.IntegrationTests/ApiTests.cs` send `Authorization: Token <jwt>`, the RealWorld convention, and `ServicesExtensions.cs` makes that work with an `OnMessageReceived` handler that strips a `Token ` prefix before the standard JWT bearer validation runs, while the Swagger definition only describes Bearer. The generated client sends `Token` so it behaves like every other RealWorld client, and the pull request says why.

To get a document rather than guess one, the agent builds and starts the API the way the repository's own scripts do: `global.json` pins SDK `10.0.402` with `latestFeature` roll-forward, `Directory.Build.props` turns on locked restore and warnings as errors, and `scripts/run-managed-api-tests.sh` shows how to run it: `dotnet build src/Conduit/Conduit.csproj -p:RestoreLockedMode=true`, then the built `Conduit.dll` with `Database__Provider=sqlite`, a temporary `ConnectionStrings__Conduit`, a generated `Jwt__SigningKey` and `ASPNETCORE_URLS`, waiting on `/api/tags`. It saves `/swagger/v1/swagger.json` as `clients/openapi.json` and generates `clients/typescript/` from it: a `schema.d.ts` of paths and components with the long `Conduit.Features.Articles.ArticlesEnvelope` names mapped to short aliases, a thin fetch wrapper that takes a base URL and a token and sets the `Token` header, and a `package.json` with a `generate` script so the client can be rebuilt from a fresh document.

Proof is a test against the running server: register a user through the client, log in, create an article, list with `limit` and `offset`, read it by slug, delete it, and assert the response types at compile time with `tsc --noEmit`. The agent also adds a check for drift: a script that starts the API, fetches the document and fails when `clients/openapi.json` differs, which the pull request describes as a candidate CI step without editing `.github/workflows/dotnetcore.yml`. The C# side is run through `dotnet run --project build/build.csproj -- test` so CSharpier and the existing xUnit suite still pass, though no C# file changes.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Generate a typed TypeScript client for this ASP.NET Core API from the Swagger document it serves. Read global.json, Directory.Build.props, src/Conduit/Program.cs (AddSwaggerGen, UseSwagger, AddJsonOptions), the conventions under src/Conduit/Infrastructure, every controller under src/Conduit/Features, the AddJwt method in src/Conduit/ServicesExtensions.cs and tests/Conduit.IntegrationTests/ApiTests.cs first. Build with dotnet build src/Conduit/Conduit.csproj -p:RestoreLockedMode=true and start the built Conduit.dll as scripts/run-managed-api-tests.sh does, with the sqlite provider, a temporary database and a generated Jwt__SigningKey, and wait for /api/tags. Save /swagger/v1/swagger.json as clients/openapi.json. Generate clients/typescript with types for every path and schema, short aliases for the full-name schema ids, a fetch wrapper that takes a base URL and a token and sends the Authorization header in the form the API's tests use, and a package.json with a generate script that rebuilds it from clients/openapi.json. Write a test that registers, logs in, creates, lists, reads and deletes an article through the client against the running server, run it and tsc --noEmit, and add a script that fails when a freshly fetched document differs from the committed one. Change no C# file; run dotnet run --project build/build.csproj -- test to confirm the repository still passes. Open a pull request with the files, the exact generator and version you used, the test output, and a note on the Token versus Bearer header.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds `clients/openapi.json`, the fetched document, and `clients/typescript/` with the generated `schema.d.ts`, the short type aliases, the fetch wrapper, a `package.json` with `generate` and `test` scripts, the test file and the drift script. No file under `src/` or `tests/` changes, so the locked restore and the xUnit suite are unaffected.

The description names the generator and the version it ran, quotes the test run against the live server with each call's status code, quotes `tsc --noEmit` passing, and explains that the client sends `Authorization: Token <jwt>` because the `OnMessageReceived` handler in `ServicesExtensions.cs` accepts that prefix and the RealWorld frontends expect it, even though the Swagger security scheme only reads Bearer. It lists the schema ids that were aliased and shows the drift script's output on an unchanged document.

A reviewer opens the wrapper to confirm the header and the base URL handling, skims the aliases for names that would confuse their frontend, and decides whether to wire the drift script into CI. The transcript keeps the server log and every request the test made.

## Run it on every change to a customer's controllers

When your product keeps a client in step with each customer's API, your server starts one run per customer repository with `POST /o/{org}/sessions`, this prompt in `input` and that customer's repository in `resources`, each run in its own sandbox with its own temporary database. A `request_id` per customer and commit makes a retry return the run it already started.

Give the key a `webhook_url` and Rush POSTs `run.completed` with `data.session_url` when the pull request is open; `GET /o/{org}/p/{project}/sessions/{id}/changes` lists the files the run changed with their diffs. A key may have at most `max_concurrent` runs in progress and starting one more answers `202` with `status: "queued"`, so a batch over many customers can start every client generation at once and let each begin when a slot frees.

## Why run it on Rush?

A client generated from a document you wrote by hand drifts from the API on the first renamed property. Generating from the document the running server emits, under the repository's own SDK pin and conventions, is the only version that cannot drift, and it needs a built and started API, a temporary database and a signing key, which the sandbox provides for every run.

The run tests the client against that server before anyone reads the pull request, so a mismatch such as the `Token` header or an explicit `null` shows up as a failed test in the transcript, not as a bug report from a frontend.

## Frequently asked questions

### Why TypeScript?

Because that is what most consumers of a RealWorld-style API are. The prompt names the language; the same run with Python or C# in place of TypeScript generates that client instead, from the same `clients/openapi.json`, with the same live test.

### Does it change the Swagger configuration to get nicer names?

No. `CustomSchemaIds` in `Program.cs` is left alone, because other consumers may depend on the full names. The generated client maps `Conduit.Features.Articles.ArticlesEnvelope` and its siblings to short aliases in one file, which is where a reviewer can rename them.

### What happens when the API prefix is not api?

`ApiRoutePrefixConvention` reads the `ApiPrefix` setting, and the integration test `Route_Prefix_Is_Configurable_And_Swagger_Remains_Available` shows the document follows it. The agent starts the server with the default, and the wrapper takes the base URL as a parameter, so a deployment on another prefix passes a different base URL rather than a regenerated client.

### Can it run the RealWorld Hurl and Bruno suites too?

Yes, when the `realworld` submodule is checked out: `make test-hurl-with-managed-server` and `make test-bruno-with-managed-server` start the server the same way. The prompt does not ask for them because they test the API, not the client, but a follow-up message to the parked session can run them.

## More ASP.NET Core jobs

- [Investigate an ASP.NET Core App Incident With Datadog](https://getrush.ai/run/investigate-incidents-with-datadog/aspnet-core/)
- [Investigate Thread Pool Starvation in an ASP.NET Core App](https://getrush.ai/run/investigate-thread-pool-starvation/aspnet-core/)
- [Turn a Jira Issue into a Pull Request for an ASP.NET Core App](https://getrush.ai/run/jira-issue-to-pr/aspnet-core/)

## The same job on other stacks

- [Generate a Typed API Client for a FastAPI Service](https://getrush.ai/run/generate-api-clients/fastapi/)
- [Generate a Typed API Client for a NestJS Service](https://getrush.ai/run/generate-api-clients/nestjs/)
- [Generate a Typed API Client for a Spring Boot Service](https://getrush.ai/run/generate-api-clients/spring-boot/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
