skills.rest
OrchardCMS
OrchardCMSOFFICIAL
Explore all skills by this author →
Website𝕏@OrchardCMSGitHub

orchardcore-nswag-regenerate

Regenerates OrchardCore OpenApi NSwag C# and TypeScript clients and verifies diff stability.

8.2k|2.6k|Updated Nov 19, 2014
Search Tags:#OpenAPI#Swagger#api client#typeScript#orchardcore#nswag#Code generation
One-click install
npx skills add https://github.com/OrchardCMS/OrchardCore --skill orchardcore-nswag-regenerate
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: orchardcore-nswag-regenerate
Source: https://github.com/OrchardCMS/OrchardCore/tree/main/.agents/skills/orchardcore-nswag-regenerate
Command: npx skills add https://github.com/OrchardCMS/OrchardCore --skill orchardcore-nswag-regenerate

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Regenerating the OrchardCore.OpenApi module's NSwag-generated API clients often produces noisy, reshuffled diffs and requires manual server setup, making it hard to tell real API changes from generation noise.

Core Features & Use Cases

  • Automated regeneration: Runs the tools/OpenApiClientGenerator console project to boot the CMS in-process, fetch swagger.json, and regenerate both the C# client (Services/OpenApiClient.cs) and TypeScript client (.scripts/bloom/services/OpenApiClient.ts).
  • Manual and offline paths: Supports running the nswag CLI against a live dev server or a scratch .nswag config pointing at a local swagger.json for reproducible, offline generation.
  • Determinism guidance: Documents the two root causes of unstable output (unsorted Swashbuckle operation order and duplicate operationIds) and how to verify stability by diffing generations from two independent tenants.
  • Use Case: After adding a new API endpoint to an OrchardCore module, regenerate the committed OpenApi clients and confirm the diff contains only your new endpoint rather than unrelated reshuffled methods.

Quick Start

Regenerate the OrchardCore OpenApi NSwag clients and verify the resulting diff is stable and contains no reshuffled methods.

Frequently Asked Questions about orchardcore-nswag-regenerate

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I regenerate the OrchardCore OpenApi NSwag clients?▼

Run dotnet run --project tools/OpenApiClientGenerator -c Release, then yarn build to refresh the Vue app's bundled JS. The tool boots the CMS in-process, fetches swagger.json, and invokes the nswag CLI to regenerate both the C# and TypeScript clients.

Why does NSwag regeneration reshuffle unrelated methods in the diff?▼

Two root causes: Swashbuckle emitted operations in non-deterministic discovery order, fixed by ordering actions by route path plus HTTP verb, and a duplicate operationId shared by GET and POST on api/queries/{name}, fixed by splitting into distinctly named actions.

Can I run NSwag generation offline without a live server?▼

Yes. Fetch swagger.json into a scratch file, copy the .nswag config, point documentGenerator.fromDocument.url at the local file, redirect outputs to scratch paths, and run nswag run on the copy. This avoids touching committed files or needing HTTPS dev certs.

Why does fetching swagger.json return 401 in OrchardCore?▼

Anonymous schema access is disabled by default in OpenApiSettings, so unauthenticated swagger.json requests are rejected. The OpenApiGeneration recipe sets AllowAnonymousSchemaAccess to true, which both the automated tool and manual NSwag path rely on.

What prerequisites are needed to run the OpenApiClientGenerator tool?▼

You need the NSwag.ConsoleCore dotnet global tool installed (dotnet tool install -g NSwag.ConsoleCore) and the .NET SDK. The tool handles tenant provisioning itself via OrchardCore.AutoSetup with the openapi-generation-setup recipe on the Default tenant.

Related Skills

Explore More Software Engineering Skills→
pkuppenspkuppens
1

api-design

Enforce REST conventions, versioning, and OpenAPI documentation for API endpoints.

Community
Intermediate
ali-masterali-master
8

oRPC Publish Client to NPM

Package and publish an oRPC client to NPM with TypeScript definitions.

Community
Intermediate
OrchardCMSOrchardCMS
8.2k

orchardcore-tester

Automate browser-based testing of OrchardCore CMS features with Playwright.

Official
Intermediate
I-SynergyI-Synergy

api-endpoints

Automate .NET Minimal API endpoint scaffolding with OpenAPI and security hardening.

Official
Advanced