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
907 stars 138 forks source link

Allow specifying an overwrite conflict strategy for the `join` command #1623

Open Carbonhell opened 2 months ago

Carbonhell commented 2 months ago

Is your feature request related to a problem? Please describe.

Hi, thank you for this amazing project! I'm using the join command to merge together the OpenAPI schemas of several AWS lambda based microservices implemented with FastAPI automatically, with a GitHub action. My problem is that I have shared component models and security scheme. Those are equal across the various microservices. For this reason, I'd assume there would be a way to resolve conflicts by merging/unifying the repeated schemas into a single one per conflict. From what I can see, I have to either edit the generated schema manually, or use custom decorators which I am still investigating.

Describe the solution you'd like A simple flag to specify conflict resolution by merging schemas together, or perhaps marking one of the input files to use when deciding how to resolve a conflict.

Describe alternatives you've considered Manually editing the resulting schema, but this weakens the value of the join command. Custom decorators look like a viable alternative, but I believe it makes sense for users to decide a conflict resolution strategy. if I understood correctly, decorators are for Redocly (SaaS), not cot Redoc/simple CLI usage

Additional context

I can try implementing this myself if others think this might be a valuable feature to have :)

lornajane commented 2 months ago

Thanks for raising this @Carbonhell . The decorators are for CLI use, and are the best way to extend the CLI. There are some additional examples in the cookbook that might give you more context in addition to the docs.

In general, you're correct, we don't try to detect when two things are in fact the same thing and then replace them both with a reference to a single item. It's a reasonably difficult problem to get right!

Your best option right now is probably to grab the components section from one of your API descriptions, declare that as a common.yaml file, and then use decorators to update the other API descriptions to point to the components in that schema. At that point, joining will probably work, but I'd love to know how you get on!