Bundle: option to keep all refs but turn them into internal refs

The bundle command’s current behaviour breaks the code generation in my current project.

Currently, with no special option, the bundle command inlines all $refs it finds on the first encounter, and then makes a reference to that local inline upon any subsequent encounter of the same reference.

For this example input:

main.yaml

swagger: '2.0'
info:
  version: 0.0.0
paths:
  /test1:
    get:
      parameters:
        - $ref: "./parameters.yaml#/parameters/param"
  /test2:
    get:
      parameters:
        - $ref: "./parameters.yaml#/parameters/param"

parameters.yaml

parameters:
  param:
    in: query
    name: myParam
    description: some demo parameter
    type: string
    pattern: '^[a-zA-Z]+$'
    required: true

The output I get from npx swagger-cli bundle main.yaml is the following:

swagger: '2.0'
info:
  version: 0.0.0
paths:
  /test1:
    get:
      parameters:
        - in: query
          name: myParam
          description: some demo parameter
          type: string
          pattern: '^[a-zA-Z]+$'
          required: true
  /test2:
    get:
      parameters:
        - $ref: '#/paths/~1test1/get/parameters/0'

When things get complicated, it can yield references like this:

$ref: '#/paths/~1analytics-ui/post/parameters/3/schema/items/properties/data/properties/page/properties/attributes'

And during code generation, this may turn into class names as long as this path, which is far from ideal.

It would be nice to have an option (e.g. --no-dereference) to preserve any reference, and simply bring the referenced declarations to the bundled file, but in a separate place within the file. This means that every reference will simply become a local declaration, but point to the same path.

Here is the output I would expect using this option on the same sample input that I provided:

bundle.yaml

swagger: '2.0'
info:
  version: 0.0.0
paths:
  /test1:
    get:
      parameters:
        - $ref: "#/parameters/param"
  /test2:
    get:
      parameters:
        - $ref: "#/parameters/param"

parameters:
  param:
    in: query
    name: myParam
    description: some demo parameter
    type: string
    pattern: '^[a-zA-Z]+$'
    required: true

Is there a way to achieve this currently?

[aaldredge]

I would also like to have this feature. Specifically for OpenAPI 3, It would be great to have an option where bundle takes the referenced components and combines them in a components section in a bundled file, updating the original $ref that pointed to <file>#<componentPath> to point to #<componentPath> in the combined file.

[pauldraper]

Copying from https://github.com/APIDevTools/swagger-parser/issues/127#issuecomment-922634697

---

The obvious – if annoying – workaround is to put components first, and reference everything there.

Example input

example.yml

openapi: "3.0.3"
components: # reference everything here
  schemas:
    a: { $ref: "./schema/a.yml" }
    b: { $ref: "./schema/b.yml" }
info:
  title: Example
  version: 0.0.0
paths:
  /a:
    get:
      responses:
        "200":
           content:
             application/json:
               schema: { $ref: "./schema/a.yml" }
           description: Success
  /b:
    get:
      responses:
        "200":
          content:
            application/json:
              schema: { $ref: "./schema/b.yml" }
          description: Success

schema/a.yml

properties:
  aName: { type: string }
  b: { $ref: "./b.yml" }

schema/b.yml

properties:
  bName: { type: string }

Example output

swagger-cli bundle example.yml

yields

openapi: 3.0.3
components:
  schemas:
    a:
      properties:
        aName:
          type: string
        b:
          $ref: '#/components/schemas/b'
    b:
      properties:
        bName:
          type: string
info:
  title: Example
  version: 0.0.0
paths:
  /a:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/a'
          description: Success
  /b:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/b'
          description: Success