Skip to content

openapi: a path item's summary and description reach the IR in no form #383

Description

@OmarAlJarrah

Summary

A Path Item Object may write summary and description. Neither reaches the IR,
whether or not the item mounts an operation, and nothing reports it.

paths:
  /p:
    summary: PATH SUMMARY
    description: PATH DESC
    get: {operationId: getX, responses: {"200": {description: ok}}}
$ morphic compile p.yaml -skip-validate | grep -c 'PATH SUMMARY'
0
$ morphic compile p.yaml -skip-validate | grep -c 'PATH DESC'
0

The operation's own Docs carries the operation's summary and description; the
path item's are read by nothing. They are declared fields of the library's model,
so they never land in the operations map either, which is why the undeclared-key
census does not see them.

Why it is not part of the census work

Every other thing a path item writes now has a home: servers, x-* and
undeclared keys are kept under Unmodeled on each operation the item mounts, or —
for an item that mounts none — on the service. summary and description are
different in kind: they are documentation, and ir.Docs is a real IR field
rather than an Unmodeled payload, so keeping them verbatim would be the wrong
shape.

What is missing is a decision about how path-item docs relate to operation docs,
and OpenAPI does not settle it: the path item's summary applies to every operation
on the path, and each operation may have its own. So a lowering has to choose
between overriding, concatenating, or holding both — and ir.Docs has one
Summary and one Description.

Options

  • Fill only when the operation writes none. Cheapest, and loses the path
    item's text whenever an operation has its own.
  • Keep both, with the path item's on a field ir.Docs does not have yet.
    Truthful; needs an IR field, which invariant 9 says should have existed from
    day one, so it wants an ir-design.md change rather than a compiler one.
  • Keep them verbatim under Unmodeled on each mounted operation, as servers
    already is. Lossless and available today, but it puts documentation in the
    channel for things with no IR home when Docs plainly is one.

Method

Found while closing the unmounted-path-item gap, by checking whether the warning
that change emits was overclaiming what it keeps. It was, and the message was
narrowed to name servers, extensions and undeclared keys only. The code at
preserveUnmountedPathItem records this issue as the reason.

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