Support joining of multiple existing `x-tagGroups` in `join` command
Nobody has claimed this yet.
- 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.
I have two or more microservices that each have their own OpenAPI specification file. I aimed to join them together to build the complete API specification.
Each service has its own tags and x-tagGroups configuration. I could not find a way to retain & merge the existing x-tagGroups from all specifications together. They are either regenerated and all tags are grouped by specification name, or just ignored, depending on the --without-x-tag-groups option.
- Builds further upon: https://github.com/Redocly/redocly-cli/issues/359
- Related, but not the same purpose: https://github.com/Redocly/redocly-cli/issues/1314
Describe the solution you'd like
I would like the final output to contain a unique list of all tag groups of every specification.
If the same tag group exists within different specifications, I would like to see their tags merged together.
I think that duplicate tags should not cause a "conflict" in this new scenario.
Maybe the current behaviour can be kept by introducing this new behaviour as a new option, or vice versa?
Describe alternatives you've considered
There is the option --without-x-tag-groups:
- If not set, it will merge all tags and group them into a
x-tagGroupwhich is based on the specification name. - If set, it will skip the above automated creation of
x-tagGroups. Unfortunately, thex-tagGroupsproperty is then not created in the joined file at all
Unfortunately this means that the existing x-tagGroups information is not used. Furthermore, you always see a warning:
warning: x-tagGroups at src/services/common/openapi.yaml will be skipped
Additional context
Example (merge A + B together, with a duplicate x-tagGroup Invoicing:
Specification A:
tags:
- name: contacts
description: Contacts
- name: companies
description: Companies
- name: invoices
description: Invoices
x-tagGroups:
- name: CRM
tags:
- contacts
- companies
- name: Invoicing
tags:
- invoices
Specification B:
tags:
- name: credit_notes
description: Credit Notes
x-tagGroups:
- name: Invoicing
tags:
- credit_notes
Intended result:
tags:
- name: contacts
description: Contacts
- name: companies
description: Companies
- name: invoices
description: Invoices
- name: credit_notes
description: Credit Notes
x-tagGroups:
- name: CRM
tags:
- contacts
- companies
- name: Invoicing
tags:
- invoices
- credit_notes
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at the join command and trace the existing --without-x-tag-groups behavior, including the warning for skipped x-tagGroups. Compare the provided Specification A and B examples, then define tests for preserving unique groups and merging tags in duplicate groups while retaining the intended current behavior or a new option.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, cli
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100