feat: add output as a per-API configuration option

[tatomyr]

What/Why/How?

Added support for the output option in the per-API configuration. This adds the possibility to store bundled files for all apis that have the option specified.

For example, for the following redocly.yaml:

apis:
   v1: 
     root: openapi1.yaml
     output: dist/v1.yaml
   v2: 
     root: openapi2.yaml
     output: dist/v2.yaml

Executing redocly bundle will store bundled files under the dist/ directory.
Executing redocly bundle openapi1.yaml will result in printing only the openapi1 bundle to stdout.

Reference

Resolves #1579

Testing

Screenshots (optional)

Check yourself

• Code changed? - Tested with redoc/reference-docs/workflows (internal)
• All new/updated code is covered with tests
• New package installed? - Tested in different environments (browser/node)

Security

• Security impact of change has been considered
• Code follows company security practices and guidelines

[changeset-bot]

🦋 Changeset detected

Latest commit: 3878eb6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@redocly/cli	Minor
@redocly/openapi-core	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
redocly lint packages/core/src/benchmark/benches/rebilly.yaml	980.0 ± 11.3	964.6	1006.4	1.00
redocly-next lint packages/core/src/benchmark/benches/rebilly.yaml	986.5 ± 21.2	957.8	1011.9	1.01 ± 0.02

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟡	Statements	78.35%	4899/6253
🟡	Branches	67.01% (+1.09% 🔼)	2021/3016
🟡	Functions	72.62%	809/1114
🟡	Lines	78.64%	4621/5876

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🟡	core/src/utils.ts	76.28%	60.76% (-1.08% 🔻)	76% (-1.55% 🔻)	77.46%

Test suite run success

793 tests passing in 118 suites.

Report generated by 🧪jest coverage report action from 3878eb6

[lornajane]

The feature behaves differently depending if we're bundling one API or many, which I did not expect. I can tell from the documentation that this is an intentional exception - but I don't know why we did this. In every other context, the API is linted/bundled the same way whether it's done alone by alias, or others are done at the same time. With this configuration, the bundle command will apply per-api decorators, but not per-api output, which seems wrong.

The command line parameter should still take priority if it's supplied, but the configuration should apply if it exists, regardless of whether there are other APIs being bundled at the same time or not.

[tatomyr]

@lornajane do you mean that having this redocy.yaml:

apis:
  main@v1:
    root: openapi.yaml
    output: bunlded.yaml

and running redocly bundle main@v1 it should store it to bundled.yaml?

[lornajane]

Yes, running redocly bundle [alias] and running redocly bundle should do the same thing for the API named by [alias].

[tatomyr]

@lornajane but how would you print it out to the stdout for the alias if needed?

[lornajane]

Oh, of course. You can't use the filename without silently picking up the alias :( I guess another alias, or a special value for --output

[tatomyr]

@lornajane another alias means you have to maintain consistency between those two (and remember twice more names too). And a special output value could collide with a filename (users are quite creative when it comes to naming things!).

[tatomyr]

I believe this option is mainly aimed for bundling and storing large amount of apis which is quite tedious to do via the command line. So that’s where the ‘output’ really comes in handy. If a user wants to bundle one alias, it’s not hard to specify the output destination as well. I hope that seeing the output, users will be able to figure out the behaviour.

[lornajane]

The current behaviour is unexpected - test it alone and you get one behaviour. Run it in a batch and it does something different. I'm not comfortable with us shipping it as it is.

[tatomyr]

@lornajane changed the behaviour. Now if you bundle an alias, it will take the output from the config if it exists.

[lornajane]

Everything here looks great to me, but I was surprised that I could bundle a file by name without it picking up the alias magically (since the file is mentioned in the config file). So I like everything here, but I wanted to mention it in case the change was not intentional.

[RomanHotsiy]

Left one comment, otherwise looks good.