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

Cerrado
  • ¿Algo no está bien?
#289 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Ya se ha fusionado un pull request relacionado.

  • #290 de @TristanSpeakEasy — fusionado

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
72/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
go, openapi
Área
backend-api-design

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
Go
Estrellas
276
Forks
21
Merge medio
1 d 6 h
PR fusionados (30 d)
23

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.