Redocly / Redocly/redocly-cli

Join command needs to join multiple spec with server prefix

Open
#1,403 11 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.

Currently the join cli command does not resolve conflicts based on paths and operationIds if we got different servers information.

Describe the solution you'd like

The join command needs to resolve this kind of conflicts using the server base url or using a custom prefix.

Describe alternatives you've considered

The alternative is to prefix manually every path and operationId to prevent conflicts, which is very verbose. The operationId is usefull if we need to generate an SDK from the specs.

Additional context

Considering different teams that are working on different microservices. Every microservices have their own servers, paths and operationId in the openapi.yaml, for example:

user.yaml for user microservice:

openapi: 3.1.0
info:
  title: User microservice
  version: 1.0.1
servers:
  - url: https://api.server.com/users
paths:
  /healthz:
    get:
      operationId: healthz
      summary: Get the status of the service
      tags:
        - users

product.yaml for product microservice:

openapi: 3.1.0
info:
  title: Product microservice
  version: 1.1.1
servers:
  - url: https://api.server.com/products
paths:
  /healthz:
    get:
      operationId: healthz
      summary: Get the status of the service
      tags:
        - products

If I run:

redocly join user.yaml product.yaml

I get the following error messages:

Conflict on paths => /healthz : get in files: user.yaml,product.yaml 
Conflict on paths => operationIds : healthz in files: user.yaml,product.yaml 
Please fix conflicts before running join.

The error is very descriptive, however in the servers section I specified different prefixes.

This behaviour limits the flexibility on every teams because they need to know if a operationId is already used in other specifications.

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 join CLI command and reproduce the conflicts using the user.yaml and product.yaml examples from the issue. Determine how server base URLs or a custom prefix should affect path and operationId conflict resolution; done means these specifications can be joined without manual prefixes while preserving distinct routes and operationIds.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.