Bundle behavior feels illogical
See original GitHub issueI 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 theshared.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
$ref
ed path parameters are dereferenced inline in thepaths:/foo:get:parameters:
section rather than just bundled. I guess it’s actually the same pattern as above. I was expectingshared.yaml#/parameters/Page
to lead to a localparameters:
section.
Issue Analytics
- State:
- Created 4 years ago
- Reactions:3
- Comments:17 (6 by maintainers)
Top Results From Across the Web
Irrational Thinking - Meaning, Beliefs, vs Rational Thinking
Irrational thinking defies reason, logic, and empirical evidence to rely on emotions, personal biases, and beliefs. It is the opposite of rational thinking....
Read more >Erratic/Inconsistent Behavior - Job Accommodation Network
Erratic/inconsistent behavior is behavior that is unpredictable, or may be considered irregular or illogical for the situation, or not keeping with the ...
Read more >Do People Bundle Sequences of Choices? An Experimental ...
Economists and psychologists have sought to model and explain both impulsive behavior and the costly but often successful mechanisms by which people control...
Read more >Guilt Me Not | Psychology Today
Feeling guilty does not help you correct troubling behavior because ... But don't leap to the illogical conclusion that therefore you are an ......
Read more >You're Not Going Crazy: 15 Signs You're a Victim of Gaslighting
Do you feel like something is "terribly wrong" but you don't know what? ... or might genuinely be exhibiting irrational behavior, it is...
Read more >Top Related Medium Post
No results found
Top Related StackOverflow Question
No results found
Troubleshoot Live Code
Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start FreeTop Related Reddit Thread
No results found
Top Related Hackernoon Post
No results found
Top Related Tweet
No results found
Top Related Dev.to Post
No results found
Top Related Hashnode Post
No results found
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
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.