Join command needs to join multiple spec with server prefix
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.
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
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 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