Skip to content

openapi: path-item summary and description reach the IR nowhere #292

Description

@OmarAlJarrah

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions