Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

`Bundle` names a path item component after the escaped JSON Pointer token (`~1users`), so its `$ref` doesn't resolve

Chiusa
  • Qualcosa non va?
#289 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Una pull request collegata è già stata integrata.

  • #290 di @TristanSpeakEasy — integrata

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
72/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
go, openapi
Ambito
backend-api-design

Direzione di ricerca

Start in openapi/bundle.go at extractSimpleNameFromReference, which the issue identifies as returning the escaped final JSON Pointer token unchanged; trace how that name is used to create the path item component and its $ref. Reproduce with the supplied /paths/~1users example, then check that the resulting component name is valid and the reference resolves. Confirm the bundled document passes openapi spec validate and openapi spec inline.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Summary

When a path item is referenced by JSON Pointer into another OpenAPI document (./paths/users.yaml#/paths/~1users), openapi.Bundle (and openapi spec bundle) uses the last pointer token as written, ~1users, as the component name. The bundled document gets components.pathItems.~1users and $ref: '#/components/pathItems/~1users'. Per RFC 6901 that ref names the key /users, which doesn't exist, and ~1users isn't a valid component name either (OAS 3.1 Components keys must match ^[a-zA-Z0-9\.\-_]+$). The bundle fails openapi spec validate, though the input passes.

Reproduction

openapi.yaml:

openapi: 3.1.0
info: {title: t, version: "1"}
paths:
  /users:
    $ref: ./paths/users.yaml#/paths/~1users

paths/users.yaml:

openapi: 3.1.0
info: {title: users, version: "1"}
paths:
  /users:
    get:
      responses:
        "200":
          description: ok

$ openapi spec bundle openapi.yaml bundled.yaml
Processing OpenAPI document: openapi.yaml
✅ Successfully bundled all external references into components section
📄 Document written to: bundled.yaml
$ cat bundled.yaml
openapi: 3.1.0
info: {title: t, version: "1"}
paths:
  /users:
    $ref: '#/components/pathItems/~1users'
components:
  pathItems:
    ~1users:
      get:
        responses:
          "200":
            description: ok
$ openapi spec validate bundled.yaml
Validating OpenAPI document: bundled.yaml
❌ OpenAPI document is invalid - 1 errors:

1. [5:11] error validation-invalid-syntax reference.$ref is invalid: invalid reference: component name "/users" must match pattern ^[a-zA-Z0-9.\-_]+$
Validation completed in 1ms
Error: openAPI document validation failed

openapi spec inline bundled.yaml fails the same way: failed to resolve reference #/components/pathItems/~1users: not found -- key /users not found in sequencedmap.Map. A path with a parameter gives ~1users~1{id}. --naming counter gives the same name.

Expected result

A valid component name and a $ref that resolves to it, as for a whole-file ref: $ref: ./paths/users.yaml (a file holding only the path item) bundles to components.pathItems.users, and the bundle validates.

Actual result

components.pathItems.~1users and a $ref that points at /users. The command reports success.

Version

v1.26.1 (main, 9f2ba11) and v1.26.0. CLI from go install github.com/speakeasy-api/openapi/cmd/openapi@latest (v0.0.0-20261029045548-9f2ba118224c); openapi.Bundle called directly gives the same output.

Cause

extractSimpleNameFromReference (openapi/bundle.go:1288) replaces characters outside [a-zA-Z0-9_] in file names, but for a fragment returns the last pointer token unchanged: not unescaped (~1, ~0) and not sanitized.

Lingua principale
Go
Stelle
276
Fork
21
Merge medio
1g 6h
PR unite (30g)
23

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Issue simili

Altre issue su Go

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.