UpDoc has its own API and always has. All three controllers declare it:
WorkflowController, DocumentTypeController, PdfExtractionController. They work — the backoffice calls them constantly.
But nothing registers the "updoc" Swagger document, so /umbraco/swagger/updoc/swagger.json returns 404 and the API is invisible to anything that reads Swagger. The attribute names a document; something still has to create it.
Confirmed against the mirror: zero occurrences of "updoc" in the Management API spec, and UpDoc did not appear in the API list when the MCP toolkit enumerated available specs.
Why it matters
It blocks #130. The MCP toolkit generates tools from a Swagger spec. With no spec, it cannot generate any UpDoc tool.
It is a gap regardless of MCP. Three controllers currently advertise a document that does not exist. Any Swagger consumer — API clients, generators, documentation tooling — is blind to UpDoc's API today.
It gives us a live API reference. Routes, parameters, request and response shapes, generated from the controllers so it cannot drift. Swagger UI also allows calling endpoints directly, which is useful for checking what extraction returns without driving the dialog.
The fix
Follow Umbraco's own pattern: an IConfigureOptions<SwaggerGenOptions> calling SwaggerDoc("updoc", new OpenApiInfo { ... }), registered in the composer.
Reference: Umbraco-CMS/src/Umbraco.Cms.Api.Common/Configuration/ConfigureUmbracoSwaggerGenOptions.cs.
Done when
Note
This ships in the RCL, unlike the MCP work in mcp/. Separate branch.
Worth checking whether the endpoints are shaped as we would want them described before publishing the document — anything exposed here becomes a contract others may rely on.
Blocks #130. Refs #129.
UpDoc has its own API and always has. All three controllers declare it:
WorkflowController,DocumentTypeController,PdfExtractionController. They work — the backoffice calls them constantly.But nothing registers the "updoc" Swagger document, so
/umbraco/swagger/updoc/swagger.jsonreturns 404 and the API is invisible to anything that reads Swagger. The attribute names a document; something still has to create it.Confirmed against the mirror: zero occurrences of "updoc" in the Management API spec, and UpDoc did not appear in the API list when the MCP toolkit enumerated available specs.
Why it matters
It blocks #130. The MCP toolkit generates tools from a Swagger spec. With no spec, it cannot generate any UpDoc tool.
It is a gap regardless of MCP. Three controllers currently advertise a document that does not exist. Any Swagger consumer — API clients, generators, documentation tooling — is blind to UpDoc's API today.
It gives us a live API reference. Routes, parameters, request and response shapes, generated from the controllers so it cannot drift. Swagger UI also allows calling endpoints directly, which is useful for checking what extraction returns without driving the dialog.
The fix
Follow Umbraco's own pattern: an
IConfigureOptions<SwaggerGenOptions>callingSwaggerDoc("updoc", new OpenApiInfo { ... }), registered in the composer.Reference:
Umbraco-CMS/src/Umbraco.Cms.Api.Common/Configuration/ConfigureUmbracoSwaggerGenOptions.cs.Done when
/umbraco/swagger/updoc/swagger.jsonreturns 200 with every UpDoc routeNote
This ships in the RCL, unlike the MCP work in
mcp/. Separate branch.Worth checking whether the endpoints are shaped as we would want them described before publishing the document — anything exposed here becomes a contract others may rely on.
Blocks #130. Refs #129.