Summary
A Path Item Object may declare summary and description, which document every operation mounted
under it. Neither is read anywhere in the compiler: fillOperationDocs reads only the Operation
Object's own summary and description, so a path item's documentation is dropped with no Unmodeled
entry and no diagnostic.
Reproduction
openapi: 3.1.0
info: {title: T, version: "1"}
paths:
/x:
summary: the path item summary
description: the path item description
get:
operationId: getX
responses: {"200": {description: ok}}
Compiles with no diagnostics at all; the resulting operation has empty Docs.Summary and
Docs.Description, and an empty Unmodeled map.
Why this needs a decision rather than a mechanical fix
Unlike the other losslessness gaps, there is no obvious destination:
- Merge into each operation's
Docs. Matches how the path item's parameters already merge
into every operation under it. But it needs a precedence rule against an operation's own summary
and description, and it invents documentation the operation did not write — closer to lowering
than to preservation.
- Keep verbatim under
Operation.Unmodeled. Consistent with how path-item servers are
handled, and takes no position on precedence. But documentation with an obvious IR home
(ir.Docs) sitting in Unmodeled is odd, and it would be duplicated onto every operation the
path item holds.
There is no ir.PathItem — a path item's contents are distributed across the operations it holds —
so whichever way it goes, the choice should be recorded before it is implemented.
Found while reviewing #272, which closes #39. Not part of that change: #39's items are all
preservation of declared wire facts, and this is a documentation-lowering decision.
Summary
A Path Item Object may declare
summaryanddescription, which document every operation mountedunder it. Neither is read anywhere in the compiler:
fillOperationDocsreads only the OperationObject's own summary and description, so a path item's documentation is dropped with no
Unmodeledentry and no diagnostic.
Reproduction
Compiles with no diagnostics at all; the resulting operation has empty
Docs.SummaryandDocs.Description, and an emptyUnmodeledmap.Why this needs a decision rather than a mechanical fix
Unlike the other losslessness gaps, there is no obvious destination:
Docs. Matches how the path item'sparametersalready mergeinto every operation under it. But it needs a precedence rule against an operation's own summary
and description, and it invents documentation the operation did not write — closer to lowering
than to preservation.
Operation.Unmodeled. Consistent with how path-itemserversarehandled, and takes no position on precedence. But documentation with an obvious IR home
(
ir.Docs) sitting inUnmodeledis odd, and it would be duplicated onto every operation thepath item holds.
There is no
ir.PathItem— a path item's contents are distributed across the operations it holds —so whichever way it goes, the choice should be recorded before it is implemented.
Found while reviewing #272, which closes #39. Not part of that change: #39's items are all
preservation of declared wire facts, and this is a documentation-lowering decision.