All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Run an agent per customer task.

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

The same job on other stacks

Keep reading