swagger-parser icon indicating copy to clipboard operation
swagger-parser copied to clipboard

Regression in v10.1.1 when fully dereferencing external $ref

Open nflaig opened this issue 1 year ago • 0 comments

I am using swagger-cli to build a json file from oapi definitions via

swagger-cli bundle ./beacon-node-oapi.yaml -r -t json -o ./deploy/beacon-node-oapi.json

Note the -r, which is used fully dereference all $ref pointers

The schema looks like this, see beacon-APIs/types/phase0/attestation_data.yaml

Phase0:
  AttestationData:
    type: object
    description: "The [`AttestationData`](https://github.com/ethereum/consensus-specs/blob/v1.3.0/specs/phase0/beacon-chain.md#attestationdata) object from the CL spec."
    required: [slot, index, beacon_block_root, source, target]
    properties:
      slot:
        $ref: "../primitive.yaml#/Uint64"
      index:
        $ref: "../primitive.yaml#/Uint64"
        example: "0" # <-- note this line
      beacon_block_root:
        $ref: '../primitive.yaml#/Root'
        description: "LMD GHOST vote."
      source:
        $ref: "../misc.yaml#/Checkpoint"
      target:
        $ref: "../misc.yaml#/Checkpoint"

primitive.yaml

Uint64:
  type: string
  example: "1"

The json output looks like this though, still containing the "1"

"index": {
    "type": "string",
     "example": "1"
},

Now I would expect the example to show "0" which with v10.1.0 was the case but no longer with v10.1.1 since swagger-cli does not pin the exact version this automatically bumped to the latest release

npm i -g @apidevtools/swagger-cli@4

Now I know this package is deprecated and we are looking to migrate soon but might be worth to report this here anyways.

Also potentially interesting, if I do not put Uint64 into an external file it works.

Current workaround is to add an override to package.json

 "devDependencies": {
    "@apidevtools/swagger-cli": "^4.0.4"
  },
  "overrides": {
    "@apidevtools/swagger-parser": "10.1.0"
  },

nflaig avatar Apr 01 '25 12:04 nflaig