UpDoc's Swagger document describes its routes but not what they return. The controllers do not declare [ProducesResponseType], so every generated client operation comes back as void and Swagger's schema section is empty.
Follows #134, which registered the document in the first place. Typed responses are the other half of having a spec.
Why it matters now
Every MCP tool has to hand-write its output schema. list-workflows (#130) already does, duplicating WorkflowSummary in TypeScript. Each new tool repeats that, and each copy can drift from the C# it mirrors.
It also weakens what Swagger is worth to a human. "Try it out" works, but the response shape has to be discovered by calling rather than read.
The work
Add [ProducesResponseType] to the controller actions in WorkflowController, DocumentTypeController and PdfExtractionController — 35 endpoints between them.
Mostly mechanical, but not blind: some actions return IActionResult with different shapes on different paths, and those want describing properly rather than being annotated with whatever the happy path returns.
Worth deciding while doing it
Anything described here becomes a contract others may rely on. Some response models were written for the backoffice and never meant to be public. Worth a look at whether any should change shape before they are published rather than after.
Done when
Refs #130, #134, #129.
UpDoc's Swagger document describes its routes but not what they return. The controllers do not declare
[ProducesResponseType], so every generated client operation comes back asvoidand Swagger's schema section is empty.Follows #134, which registered the document in the first place. Typed responses are the other half of having a spec.
Why it matters now
Every MCP tool has to hand-write its output schema.
list-workflows(#130) already does, duplicatingWorkflowSummaryin TypeScript. Each new tool repeats that, and each copy can drift from the C# it mirrors.It also weakens what Swagger is worth to a human. "Try it out" works, but the response shape has to be discovered by calling rather than read.
The work
Add
[ProducesResponseType]to the controller actions inWorkflowController,DocumentTypeControllerandPdfExtractionController— 35 endpoints between them.Mostly mechanical, but not blind: some actions return
IActionResultwith different shapes on different paths, and those want describing properly rather than being annotated with whatever the happy path returns.Worth deciding while doing it
Anything described here becomes a contract others may rely on. Some response models were written for the backoffice and never meant to be public. Worth a look at whether any should change shape before they are published rather than after.
Done when
npm run generateinmcp/produces typed operations rather thanvoidlist-workflowsuses the generated schema instead of its hand-written oneRefs #130, #134, #129.