feat: adds useSchemaTitleAsRef in the bundler

[kennethaasan]

What/Why/How?

First of all, thank you for creating redoc/redocly. We already have quite a big codebase with schemas used in AsyncAPI specs, and now we want to use the redoc documentation and redocly bundler for some of our OpenAPI specs. This seems to be the only blocker for us.

Reference

Please see #661. We're not able to use the bundler because it uses the file names instead of the schema titles as references.

Testing

Added a test in packages/core/src/__tests__/bundle.test.ts

Screenshots (optional)

Check yourself

• Code changed? - Tested with redoc/reference-docs/workflows (internal)
• All new/updated code is covered with tests

Security

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

[changeset-bot]

🦋 Changeset detected

Latest commit: d00d6c9

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

This PR includes changesets to release 2 packages

Name	Type
@redocly/openapi-core	Minor
@redocly/cli	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

[lornajane]

Thanks @kennethaasan! I think we need to consider if title makes the most sense in the widest number of situations. I am concerned about two things:

• in general, we try not to add configuration options since it's very easy to quickly get too many to be useful
• assuming that the title field is present and unique is not a given, repurposing data might not solve the problem for most users.

[kennethaasan]

Hey @lornajane, thanks for taking a look. I saw #1496, but for us title makes more sense than the path. What if we combine the two and use title if it exists, and path as a fallback?

Regarding configuration options, I think we can make this (1. title, 2. path) the default behavior. Based on what I see in #1496, the current approach with file name is the least best option.

What do you think? The only alternative we have is to make our own bundler which I would like to avoid.

[adamaltman]

@kennethaasan you are proposing a breaking change. @lornajane's PR is also a breaking change (albeit less of one).

[kennethaasan]

Yes, but it doesn't have to be. Initially, I proposed adding it as a configuration option. I can imagine having it as a configuration option makes sense because different users might want different names.

[lornajane]

How about adding an extension field to indicate to bundle how to name the schema, to avoid letting the tool guess the name in situations where it can't guess correctly? I said that I didn't think it was great to re-use title, but x-component-schema-name or something would be very specific, wouldn't break anything for anyone not using it, and would give the control that I think you're asking for @kennethaasan .

(let's not finalise that naming without discussion and checking if there's anything already in use that does the same thing)

We can also consider improving the name-guessing and reduce the warnings as separate ideas.

[kennethaasan]

Do you mean you must set that extension field in each schema then? We already have quite a big code base with JSON schemas used for AsyncAPI where we bundle with the title, and we want to re-use those schemas when bundling OpenAPI specs and use the title there as well. Setting an extension in each schema will not work for us because it's too much boilerplate and duplicated work. I'm happy to create our own bundler, but I was hoping to use this one :/

[tatomyr]

@adamaltman I don't think it's a breaking change.

@kennethaasan please correct me if I'm wrong, but you've merely added the useSchemaTitleAsRef option (default to false) to the bundle function which I consider a minor change. However, if we were to add a new option, I believe users should be able to add that option through the CLI interface. Also, that needs to be documented.

Another question, what behaviour you would expect if the options are set to true but there's no title in a schema? (I'd not mix titles and filenames since there may be collisions between those two either). What approach to choose when titles contain special symbols (e.g. spaces, slashes &c.)?

[adamaltman]

@tatomyr why wouldn't it be a breaking change? (I'm talking about changing the default behavior, not a configuration option. We have clients that rely on the bundle to generate SDKs, etc...)

A configuration option though is also a cognitive load change. That's why it warrants time and discussion.

Is this the configuration option that is going to drive more usage and adoption? I think it may help @kennethaasan but I don't think this is going to be widely used.

Configuration options like those cause decay in the applications usability to new users -- and therefore, could actually hinder more usage and adoption. Sorry Kenneth, I don't mean anything negative by this, but imagine we should provide people with a list with 100 configuration options for the bundle command. They all become ignored by the majority of people. New options also have sustained engineering costs to consider.

I'm for new options -- but I'd like to see them being used by at least 2-5% of the user base.

[tatomyr]

why wouldn't it be a breaking change? (I'm talking about changing the default behavior, not a configuration option. We have clients that rely on the bundle to generate SDKs, etc...)

I mean that the default bundler behaviour is not changing as far as I can judge based on the code changes.

[lornajane]

@kennethaasan (going back a few steps in the discussion, hopefully this isn't too disjointed). If we added a specific extension field and used that for the name if it's present, that's not a breaking change. If you already have the information in place in title or a similar field, I'd suggest you add a custom plugin to create the new field automatically before bundling.

Let me know if an example would be useful.

[kennethaasan]

Sorry for the late response (I've been on holiday). If you think almost no one needs this, I agree with @adamaltman that this should perhaps not be added here. We will instead create and maintain our own bundler.

[kennethaasan]

Closing because we made our own bundler that re-uses lots of your bundler.