Bundle behavior feels illogicalSee original GitHub issue
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.
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' ...
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)
#/responsessection in the output from the
shared.yaml#/responsesreferences 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/Pageto lead to a local
- Created 3 years ago
- Comments:17 (6 by maintainers)
Top GitHub Comments
@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