Orchardcore Nswag Regenerate

OrchardCore NSwag Regenerate

Regenerates the OpenApi module's NSwag-generated C#/TypeScript API clients and verifies the regeneration produces a stable, non-reshuffled diff.

Preferred: tools/OpenApiClientGenerator (automated, no browser/dev-server needed)

A console project that does the whole pipeline headlessly:

dotnet run --project tools/OpenApiClientGenerator -c Release
yarn build   # refreshes the Vue app's bundled JS against the new TS client

It boots the CMS in-process on an ephemeral port, uses OrchardCore.AutoSetup with src/OrchardCore.Cms.Web/Recipes/openapi-generation-setup.recipe.json (issetuprecipe: true) to provision the Default tenant with the same feature set as openapi-generation.recipe.json below, fetches swagger.json, writes a scratch .nswag config pointing at that capture, and shells out to the nswag CLI (same prerequisite as the manual path: dotnet tool install -g NSwag.ConsoleCore). Source: tools/OpenApiClientGenerator/Program.cs.

Why Default tenant specifically: OrchardCore.Tenants (and .Distributed, .FeatureProfiles) have DefaultTenantOnly = true in their [Feature] manifest attribute — they can only be enabled on the Default/Host shell, never a secondary tenant. A Blog-recipe functional-test tenant cannot enable OrchardCore.Tenants, which is why this tool targets the Default shell via AutoSetup rather than reusing the functional-test harness's tenant pattern.

This tool only regenerates the clients against whatever API surface the current source produces — it does not add a CI drift-check gate (that was scoped out; see nswag-automation-plan.md in git stash history for the fuller original proposal, "Part 1" of which this tool implements).

The manual procedure below still applies if you need to regenerate against a real running dev server (e.g. to inspect swagger.json interactively) or investigate the tool's own behavior.

Where things live

• Config: src/OrchardCore.Modules/OrchardCore.OpenApi/OrchardCore.OpenApi.nswag — this file already exists, do not assume it's missing. It defines both generators:
  • openApiToCSharpClient → outputs Services/OpenApiClient.cs (relative to the module folder)
  • openApiToTypeScriptClient → outputs ../../../.scripts/bloom/services/OpenApiClient.ts
• Source document: documentGenerator.fromDocument.url points at a running instance's Swashbuckle endpoint, https://localhost:5001/swagger/v1/swagger.json. NSwag also accepts a local file path in this same field instead of a URL — useful for reproducible/offline generation (see below).
• Recipe: src/OrchardCore.Modules/OrchardCore.OpenApi/Recipes/openapi-generation.recipe.json (name OpenApiGeneration) enables every feature that exposes an API endpoint: OrchardCore.Contents, OrchardCore.Queries, OrchardCore.Tenants, OrchardCore.Search.Lucene, OrchardCore.Search.Elasticsearch, OrchardCore.OpenApi. It also contains a Settings step setting OpenApiSettings.AllowAnonymousSchemaAccess: true — anonymous schema access is disabled by default (the middleware returns 401 for unauthenticated swagger.json fetches), and both NSwag paths below fetch the schema anonymously. The setup recipe used by the generator tool (openapi-generation-setup.recipe.json) has the same step. Note the Settings step replaces the whole stored OpenApiSettings object, wiping any OAuth configuration on the tenant it runs on — fine for throwaway generation tenants, worth knowing on a configured one.
  • It has "issetuprecipe": false, so it does not appear in the new-tenant/site-setup recipe dropdown. Run it against an already-set-up tenant instead, via Admin ▸ Configuration ▸ Recipes, click "Run" next to "OpenApi Generation", confirm the modal. (/Admin/Recipes, AdminController.Execute in OrchardCore.Recipes.)

Manual procedure (fallback)

NSwag CLI

Installed as a dotnet tool: ~/.dotnet/tools/nswag (or dotnet tool install -g NSwag.ConsoleCore if missing). Run with:

nswag run src/OrchardCore.Modules/OrchardCore.OpenApi/OrchardCore.OpenApi.nswag

This requires a live server at the configured url. For a real regeneration that updates the committed files, run the actual local dev server, set it up with the OpenApiGeneration recipe, and run the command above unmodified.

Reproducible / offline generation (for testing determinism, without touching committed files)

1. Fetch swagger.json from a running instance into a scratch file.
2. Copy the .nswag config, and in the copy only change documentGenerator.fromDocument.url to the scratch file's path, and both generators' output to scratch paths. Do this with a small Python/jq one-liner rather than hand-editing — the config is plain JSON.
3. nswag run <scratch-config>.

This lets you diff two independent generations without ever touching the real generated files or needing HTTPS/dev-cert setup.