Redocly / Redocly/redocly-cli

Use `+` as marker for path parameters when splitting a specification

Open
#1,336 12 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

p3 split Type: Enhancement
Dominant language
TypeScript
Stars
1.5k
Forks
228
Avg merge
1d 14h
Merged PRs (30d)
48

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the openapi split openapi-bundle.yaml --outDir ./split command and the generated path-file naming behavior described in the issue. Reproduce a split specification containing a path parameter, then trace the CLI entry point that creates those filenames. Done means generated path files use + instead of {} while remaining usable for the documented endpoint references.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, typescript
Domain
cli
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.