skills.rest
umbraco
umbracoOFFICIAL
Explore all skills by this author →
WebsiteGitHub

umb-update-openapi

Regenerates the Umbraco Management API OpenApi.json and backoffice hey-api client from a running backend.

5.2k|2.9k|Updated Jun 10, 2013
Search Tags:#OpenAPI#API client generation#spec sync#typeScript#Umbraco#DotNet#hey-api
One-click install
npx skills add https://github.com/umbraco/Umbraco-CMS --skill umb-update-openapi
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: umb-update-openapi
Source: https://github.com/umbraco/Umbraco-CMS/tree/main/.claude/skills/umb-update-openapi
Command: npx skills add https://github.com/umbraco/Umbraco-CMS --skill umb-update-openapi

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

When Management API controllers, endpoints, or view models change in Umbraco CMS, the committed OpenApi.json and the generated backoffice TypeScript client silently go stale. This Skill automates the byte-for-byte refresh of the OpenAPI spec from a running backend and keeps the generated hey-api client in sync, replacing the old manual copy-paste routine.

Core Features & Use Cases

  • Byte-for-byte spec refresh: Fetches the OpenAPI document from the running backend's /umbraco/openapi/management.json endpoint and writes it directly to src/Umbraco.Cms.Api.Management/OpenApi.json via npm run generate:openapi.
  • Backend lifecycle management: Probes port 44339, starts a Development backend if none is running, and cleanly stops only the instance it started.
  • Client synchronization check: Regenerates the backoffice hey-api client with npm run generate:server-api and reads the git diff to detect drift between the committed spec and generated types.
  • Use Case: After adding a new Management API endpoint, ask the assistant to sync the OpenAPI spec — it restarts or reuses the backend, fetches the updated document, shows the diff, and regenerates the client types so your frontend code compiles against the new API.

Quick Start

Ask the assistant to sync the OpenAPI spec and regenerate the backoffice API client after changing any Management API endpoints.

Frequently Asked Questions about umb-update-openapi

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

FAQPage Schema
How do I regenerate the Umbraco Management API OpenApi.json?▼

Run the backend in Development mode, then execute npm run generate:openapi from the Umbraco.Web.UI.Client project. It fetches the document from /umbraco/openapi/management.json on port 44339 and writes it byte-for-byte into src/Umbraco.Cms.Api.Management/OpenApi.json.

How do I update the Umbraco backoffice hey-api client after changing endpoints?▼

Run npm run generate:server-api in src/Umbraco.Web.UI.Client after refreshing OpenApi.json. The generator reads only the committed spec file, then check git diff on the backend-api package to confirm the client matches the current API surface.

Why does the Umbraco OpenAPI endpoint return 404 on a running backend?▼

A 404 from an otherwise healthy Umbraco instance means the backend is running in Production, where the OpenAPI document is not mapped. Restart it with the Development environment to expose /umbraco/openapi/management.json.

Why is my new endpoint missing from the regenerated OpenApi.json?▼

Controllers marked with [ApiExplorerSettings(IgnoreApi = true)], such as the back-office security endpoints, are excluded by design. Otherwise the running build is stale — rebuild and restart the backend so the fetched document reflects your latest code.

Does this apply to Umbraco Delivery API changes?▼

No. This workflow covers only the Management API spec and its backoffice client. Delivery API changes and internal service or repository edits that do not alter the Management API surface are out of scope.

Related Skills

Explore More Software Engineering Skills→
umbracoumbraco
26

umbraco-openapi-client

Generate an OpenAPI client with bearer token authentication for Umbraco backoffice APIs.

Official
Advanced
atilladenizatilladeniz
2

api-generation

Generate typed TypeScript API clients from Go Swagger comments.

Community
Intermediate
oskar-dragonoskar-dragon

canary-workflow

Update OpenAPI-generated TypeScript types and client code across a monorepo.

Community
Intermediate
SaintForeSaintFore

openapi-type-safe-sync

Generate TypeScript types and React Query hooks from openapi.json.

Community
Intermediate