Bundle behavior feels illogical

I only recently learned about the bundle command and it promised to be exactly what I was looking for. After taking it for a test ride I’m left with mixed feeling. There’s some behavior that feels illogical to me. However, there may be perfectly sensible explanations for what I’m seeing.

API file

swagger: '2.0'
info:
  version: "1.0"
  title: test API
paths:
  /foo:
    get:
      summary: Find foos
      parameters:
        - $ref: 'shared.yaml#/parameters/Page'
        - $ref: 'shared.yaml#/parameters/PageSize'
        - $ref: 'shared.yaml#/parameters/Sort'
        - name: topic
          in: query
          description: topic
          required: false
          type: string
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/Foo'
        400:
          $ref: 'shared.yaml#/responses/clientErrorMessage'
        500:
          $ref: 'shared.yaml#/responses/internalErrorMessage'
  /bar:
    get:
      summary: Returns all bars
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Bar"
        400:
          $ref: 'shared.yaml#/responses/clientErrorMessage'
        500:
          $ref: 'shared.yaml#/responses/internalErrorMessage'
definitions:
  Bar:
    type: object
    required:
      - channel
    properties:
      channel:
        type: string
  Foo:
    type: object
    required:
      - id
    properties:
      id:
        type: integer
        format: int64

shared.yaml The content of the file shared across multiple APIs contains the expected stuff. Snippet:

parameters:
  Page:
    name: page
    in: query
    minimum: 1
    type: integer
    default: 1
    required: false

...
responses:
  internalErrorMessage:
    description: yadayada
    schema:
      $ref: '#/definitions/InternalError'
...

Bundled result I run swagger-cli bundle --outfile bundle.yaml --type yaml api.yaml && swagger-cli validate bundle.yaml and verify the output. bundle.yaml is reported to be valid, that’s cool.

• Oddity 1: rather than creating a (shared) #/responses section in the output from the shared.yaml#/responses references the bundler dereferenced the response once and then points from a response in one path to the response in the other $ref: '#/paths/~1bar/get/responses/400'. It’s certainly valid OpenAPI but it doesn’t feel clean to me.
• Oddity 2: the $refed path parameters are dereferenced inline in the paths:/foo:get:parameters: section rather than just bundled. I guess it’s actually the same pattern as above. I was expecting shared.yaml#/parameters/Page to lead to a local parameters: section.

[philsturgeon]

@marcelstoer we have written functionality that creates the sort of bundle you want, it’s built into the whole Stoplight ecosystem: Platform, Explorer, Studio, etc.

Whilst we do help maintain a few repos for APIDevTools, most of our focus has been on json-schema-ref-parser as we use it, but swagger-parser not so much. I’m doing what I can, but not actively developing complex functionality.

Anyway, the functionality for tidy bundling is hidden in a fork we quickly put together as we were struggling to get changes upstream at the time, and I’ve asked the developers to either a) document the functionality in the fork, or b) merge the changes upstream. You can keep track that over here. https://github.com/stoplightio/json-schema-ref-parser/issues/27

[ChuckJonas]

I think you could do some preprocessing before bundling to setup @pauldraper’ workaround so you don’t have to do it manually…

It would be amazing if the bundle method had an option to do this for you.