Redocly / Redocly/redocly-cli

Being able to customize the split operation to have finer control on the produced file structure

Open
#2,059 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Is your feature request related to a problem? Please describe.
split command produces rather standard output file structure :

outputFolder :
| openapi.yaml
|___ components
| |___headers
| |___schemas
|___paths

For most cases it works perfectly fine and the produced file are sufficiently small / focused on one particular object.
However there may be cases where the output files are still rather big.
Typically; when describing the various end points of a path, we have in a single file requestBody + responses associated to the path :

requestBody:
description: ipsum lorem xxxx
content:
application/json:
schema:
$ref: ../components/schemas/post.yaml
examples:
basicRequest_01:
...
basicRequest_02:
...
advancedRequest_01:
..
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: ../components/schemas/post_200.yaml
examples:
....
...
'400':
description: Bad request, invalid input.
content:
application/json:
schema:
$ref: ../components/schemas/post_400.yaml
examples:
...

In case the ressource has significant number of attributes and if multiple examples are provided, the file is not that much small and readable anymore.

May be I missed something in documentation of the split command but I did not see how I could, for example have a particular configuration to split further examples in dedicated files.

Describe the solution you'd like

I would like to be able to configure more precisely the way the split in particular for the examples (bodyRequets/responses) is done either through command line with additional argument, or through configuration file to decide to split them as separate files or keep them along with body request/response of the parent path item.

Describe alternatives you've considered
For now I manually extract the examples and place them in separate file and reference them.

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 split command and its documentation; the issue names no implementation files or tests. Determine how command-line arguments or configuration could control example extraction, then verify that the generated file structure matches the selected behavior while preserving the existing default.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
api, cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
32/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.