Redocly / Redocly/redocly-cli

Support joining of multiple existing `x-tagGroups` in `join` command

Open
#1,707 0 comments 3 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.

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.

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-tagGroup which is based on the specification name.
  • If set, it will skip the above automated creation of x-tagGroups. Unfortunately, the x-tagGroups property 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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.