Resolve references to other path operations' examples

[jjjasper]

Resolve references to other path operations' examples (as created by swagger-cli)
eg #/paths/~1client-api~1v2~1accounts~1balance-history~1%7BarrangementIds%7D/get/responses/200/content/text~1csv/example
(fixes: #226)

[ntgussoni]

I have no particular comments on this, the code seems fine but I wonder if referencing the path is part of the specification or we are bending the rules.
I ask this because this change also implies making sure boat docs render this properly and also boat marina.
I know we have these kinds of references everywhere and right now appear broken, i'd like @bartveenstra to take a look at it as well.

[jjjasper]

I have no particular comments on this, the code seems fine but I wonder if referencing the path is part of the specification or we are bending the rules.
I ask this because this change also implies making sure boat docs render this properly and also boat marina.
I know we have these kinds of references everywhere and right now appear broken, i'd like @bartveenstra to take a look at it as well.

Yes, these references are part of the standard (see https://swagger.io/docs/specification/using-ref/)
Developers are not writing these links afaik, the swagger-cli bundling the specs adds these refs. (When using BOAT bundler the example is put in /components/examples and referred to there)

[ntgussoni]

I think that these examples should be turned into components if they are going to be reused but apart from that, i remember the docs template use the jsonSchema property which contains references as well. Will these get resolved?

Sorry I cannot test this now, so my question might be dumb but im officially on vacation and from my phone :p

[jjjasper]

I think that these examples should be turned into components if they are going to be reused but apart from that, i remember the docs template use the jsonSchema property which contains references as well. Will these get resolved?

Sorry I cannot test this now, so my question might be dumb but im officially on vacation and from my phone :p

The source API spec probably has multiple endpoints referencing to a single example that is defined in a separate file. The weird looking reference are created by the tooling used to bundle the spec.

This fix only addresses the example references.

Enjoy your holiday!

[bartveenstra]

In the car at the moment, so I'll zoom in a bit later . The paths are valid yaml, and many tools will parse them ,but our apis are meant for humans so I think we should still start gating on apis that are bundled with paths with tildes .

This fix only applies to boat docs and marina?

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
1 Code Smell

81.6% Coverage
0.0% Duplication