search

Redocly / redocly-cli

⚒️ Redocly CLI makes OpenAPI easy. Lint/validate to any standard, generate beautiful docs, and more.
https://redocly.com/docs/cli/
MIT License
852 stars 129 forks source link

Allow split command to group by naming convention then write each group to their own file. #1514

Closed mdh09 closed 4 weeks ago

mdh09 commented 2 months ago

We have naming conventions to our schemas and would like to know if it's possible to group schemas with similar naming conventions together. By naming convention, we have schemas like Architype.Date, Architype.Name, Models.Contracts, Models.Vehicles, Properties.StopDate, Properties.ContractNumber. Properties schemas usually $ref an Architype schema. Model schemas usually $ref multiple Properties schemas.

The split command is great in that there's not a single giant file, but having hundreds of little files makes navigation a nightmare.

Having the ability to group schemas with the same conventions (Architype, Models, Properties, etc) into the same file would lessen the numbers of files created by the split's default functionality. By this I mean, all the Architype schemas go into a single Architype.json file; all the Properties schemas would go into a single Properties.json file; etc...

As to what that would look like: Option 1. Add a new extension x-SchemaGroup. This extension would be added to each of the schemas. An example would be: SchemaGroupExtensionExample The split command would have an option --SplitBySchemaGroup and the process would group by the extension and create 1 file per x-SchemaGroup defined.

Option 2. Lean on the Name of the schemas. For example, only allow a schema name to have 1 or maybe 2 delimiters. This would be the . in the following case. image From there, the process would be similar to option 1 only that instead of grouping by the extension, the grouping be by the first word before the delimiter.

There could be more options, but these 2 were the most transparent options in my head.

Thank you in advance!

tatomyr commented 2 months ago

Hi @mdh09! Could you explain how you use the split command? Is the split code going to be your source of truth? What do you use the bundled and split versions for? Why does having many separate files make it difficult to navigate (I'd expect the opposite 🙂)?

Note: there is a similar request: https://github.com/Redocly/redocly-cli/issues/1502

lornajane commented 4 weeks ago

Closing due to inactivity.