Use + as marker for path parameters when splitting a specification

[meden]

Describe the bug

When splitting an existing specification, and individual path files are generated, the parameters in path are enclosed in {} in the names of corresponding generated path files.

The characters { and } need escaping when referred in Linux shell, and this makes harder to manage them.

To Reproduce
Steps to reproduce the behavior:

1. Given any working redocly.yaml file
2. Given any valid openapi-bundle.yaml file having at least one endpoint with path parameters
3. Run openapi split openapi-bundle.yaml --outDir ./split
4. Try to refer a path file relative to an endpoint with a path parameter: it will require something like paths/book_\{bookId\}.yaml

Expected behavior

It would be preferable to have filenames without special characters in their names.

A good candidate seems to be #+, as it looks like it is not needing any escaping in Windows. To preserve retro-compatibility, the marker character could eventually be configurable.

Redocly Version(s)

1.0.0-beta.125

Node.js Version(s)

v18.13.0

[meden]

Spoke too soon... The # is indeed reserved in references. + could be an alternative.

[tatomyr]

Hi @meden,
I don't think this is a bug, rather an enhancement 🙂
I wouldn't change the default behaviour but allow to configure the characters with some option or through the config file. Not sure about the syntax though.

[tatomyr]

Note: This might be tangentially related to #1285.

[meden]

I don't think this is a bug, rather an enhancement

@tatomyr definitely, sorry for using the wrong template.

I wouldn't change the default behaviour but allow to configure the characters with some option or through the config file. Not sure about the syntax though.

Indeed it would be the "safest" and most flexible solution. A possible way to do it could be something like a parameter:

--paramEnclosing=<openingChar><closingChar>

E.g. the current behavior would correspond to the parameter:

--paramEnclosing={}

Having no enclosing characters should also be allowed.

[adamaltman]

Try to refer a path file relative to an endpoint with a path parameter: it will require something like paths/book_{bookId}.yaml

When you say "refer" do you mean using $ref or something else? Because our $ref resolver works fine on Linux without needing to escape.

Here is a working example:

https://github.com/Rebilly/api-definitions/blob/main/openapi/openapi.yaml#L621-L622

[meden]

$ref resolver works fine on Linux without needing to escape.

I'm not talking about escaping in YAML, but referring the file in a shell (e.g. by hitting TAB to auto-complete its name).

I'm asking to have a way to produce file names without special characters.

BTW, at least with this IntelliJ IDEA plugin, using curly braces in $refs causes parsing issues nonetheless, so the requested ability is needed also to prevent this.

[thesteve0]

Ran into this issue as well. I actually do think it is a bug. The CLI is creating invalid URIs. I spent quite a bit of time

1. Figuring out this was the issue
2. Deciding how to fix it
3. Then fixing it - requires both changing the file name and the ref in the OpenAPI.json.

Default behavior should produce valid URIs and then let people change it to { } if that's what they want.

[thesteve0]

~ seems to be a good character and it is infrequently used in text

https://www.rfc-editor.org/rfc/rfc3986#page-13

[lornajane]

Changing the default behaviour is probably not an option until the next major release, since it will break a large number of existing workflows. However I think either + or ~ should be considered as an optional parameter to use so that we can make this functionality available sooner.

[thesteve0]

Sounds good, just allowing an alternative option would be great. In the end I blame the spec writera for their not specifying a format that is a valid uri 😄

…

On Tue, Jun 4, 2024 at 2:16 AM Lorna Jane Mitchell ***@***.***> wrote: Changing the default behaviour is probably not an option until the next major release, since it will break a large number of existing workflows. However I think either + or ~ should be considered as an optional parameter to use so that we can make this functionality available sooner. — Reply to this email directly, view it on GitHub <#1336 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKWZQ3CN2T2EDA2MI7T3D3ZFWAYNAVCNFSM6AAAAAA7TECLEKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNBXGAZDINJTHA> . You are receiving this because you commented.Message ID: ***@***.***>

[thesteve0]

Found another parsing library in Python that also throws exceptions when there is a {} in the ref path.

https://github.com/manchenkoff/openapi3-parser

('Invalid reference path paths/accounts_{id}.yaml',)

[tatomyr]

I think it’s a broader issue. There are also problems with certain symbols on Windows. We might need a configuration option for the split command in redocly.yaml, something like this:

split:
  '{': '+'
  '}': '+'
  ':': _

This could also be a good place to configure the root path item (/) folder (see this issue).

@RomanHotsiy @adamaltman what do you think?