Skip to content

fix(codegen): traverse references in all supported OpenAPI fields - #2554

Open
abramchikd wants to merge 1 commit into
oapi-codegen:mainfrom
abramchikd:fix/complete-openapi-ref-traversal
Open

abramchikd wants to merge 1 commit into
oapi-codegen:mainfrom
abramchikd:fix/complete-openapi-ref-traversal

Conversation

@abramchikd

Copy link
Copy Markdown

fix(codegen): traverse references in all supported OpenAPI fields

Summary

Extend the codegen reference walker so component pruning discovers references
from all SchemaRef-bearing fields supported by the current kin-openapi model,
as well as from webhooks and nested media-type content.

Previously, a component referenced only from an OpenAPI 3.1 JSON Schema keyword,
an OpenAPI 3.2 itemSchema, a webhook, header content, or an encoding header
could be treated as unused and removed from components.

Problem

pruneUnusedComponents determines which components are reachable through
findComponentRefs, which in turn uses the shared walkSwagger traversal.
That traversal covered the original OpenAPI 3.0 schema locations but did not
keep pace with fields added to kin-openapi for OpenAPI 3.1 and 3.2.

For example, the reference in this OpenAPI 3.1 schema was not visited:

components:
  schemas:
    Text:
      type: string
    Container:
      type: object
      propertyNames:
        $ref: '#/components/schemas/Text'

The same problem affected references under prefixItems, contains,
patternProperties, dependentSchemas, unevaluatedItems,
unevaluatedProperties, if/then/else, $defs, and contentSchema.

Root-level webhooks were also skipped. In addition, media-type traversal did not
visit OpenAPI 3.2 itemSchema, schemas inside Header.Content, or headers nested
under MediaType.Encoding.

Changes

  • Visit root-level webhooks using the same path-item traversal as normal paths.
  • Continue walking components when an OpenAPI 3.1 document omits paths.
  • Centralize traversal of child schema references in schemaChildRefs.
  • Cover every SchemaRef-bearing field currently exposed by
    openapi3.Schema, including the OpenAPI 3.1 JSON Schema keywords.
  • Centralize media-type traversal in walkContent.
  • Visit both schema and OpenAPI 3.2 itemSchema in media types.
  • Visit schemas and examples nested in parameter, request-body, response, and
    header content.
  • Visit headers nested under media-type encodings.
  • Reuse path-item traversal for callbacks.

Scope

This change does not add a local workaround for kin-openapi's lossy
SchemaRef.MarshalJSON behavior with OpenAPI 3.1 $ref sibling keywords.
Preserving the original sibling fields, including explicitly empty values and
self-referential schemas, requires a fix in kin-openapi because the relevant
source-presence information is stored in private SchemaRef fields.

Once kin-openapi preserves those fields during marshaling, oapi-codegen's
existing embedded-spec flow can continue to internalize external references and
marshal the document without clearing $ref or implementing its own cycle
detection.

This pull request was created with the assistance of OpenAI Codex.

@abramchikd
abramchikd requested a review from a team as a code owner September 15, 2026 08:52
@greptile-apps

greptile-apps Bot commented Sep 15, 2026

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

The PR appears safe to merge, with no concrete correctness, security, or repository-rule violations identified.

Summary

This PR expands component-reference discovery across newer OpenAPI schema fields and additional operation/content locations.

  • Traverses OpenAPI 3.1 schema keywords, $ref siblings, and OpenAPI 3.2 media-type item schemas.
  • Adds webhooks, header content, and encoding-header traversal.
  • Reuses centralized schema, content, and path-item walkers.
  • Adds focused regression tests for pruning and reference discovery.

Reviews (1) · Last reviewed commit: "fix/complete-openapi-ref-traversal"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant