Join produces valid yaml but invalid semantics

[AndreasBergmeier6176]

Describe the bug

Join produces invalid OpenAPI doc. Especially bad because it does not notify user that the result will very likely be unexpected.

To Reproduce Steps to reproduce the behavior:

1. Run redocly join with these two (non-conflicting) files:

openapi: 3.1.1

paths:
  /foo:
    get:
      summary: Get Foo
servers:
  - url: https://foo.com/api/v1/first

and

openapi: 3.1.1

paths:
  /bar:
    get:
      summary: Get bar
servers:
  - url: https://foo.com/api/v1/second

2. See invalid result

openapi: 3.1.1

paths:
  /bar:
    get:
      summary: Get bar
  /foo:
    get:
      summary: Get Foo
servers:
  - url: https://foo.com/api/v1/first
  - url: https://foo.com/api/v1/second

This OpenAPI cannot be used to generate anything since it is just plain invalid.

Expected behavior

Either it needs to be smart enough to detect common anchored server URLs and output:

openapi: 3.1.1

paths:
  /first/foo:
    get:
      summary: Get Foo
  /second/bar:
    get:
      summary: Get bar
servers:
  - url: https://foo.com/api/v1

or it needs to detect that it cannot possibly join these files to a valid output and issue an error:

Cannot join documents containing different servers URLs to a valid output. If you want the operation to happen anyways use commandline option --ignore-semantics

[jeremyfiel]

Couple things

• the yaml is valid
• a definition can have more than one unique basepath defined, that's why it's an array of servers

Can you explain in more detail what you are generating and why you think nothing useful can be generated?

Where is the bug? The implementation may not produce what you require, but I'm not sure a bug exists.

The join command is not a code generator, Redoc is probably considered the main output target. It is understandable that the definition may be used for other purposes than docs.

[AndreasBergmeier6176]

Ok, we probably need to create an own semantic tool then if that is out of scope for redocly. We have multiple teams that have this requirement.

[RomanHotsiy]

I think it can work in a simpler way by leveraging servers on the path level:

openapi: 3.1.1

paths:
  /bar:
    servers:
      - url: https://foo.com/api/v1/second
    get:
      summary: Get bar
  /foo:
    servers:
      - url: https://foo.com/api/v1/first
    get:
      summary: Get Foo

@AndreasBergmeier6176 would it work for your use case?

[AndreasBergmeier6176]

I think it can work in a simpler way by leveraging servers on the path level:

openapi: 3.1.1

paths:
  /bar:
    servers:
      - url: https://foo.com/api/v1/second
    get:
      summary: Get bar
  /foo:
    servers:
      - url: https://foo.com/api/v1/first
    get:
      summary: Get Foo

@AndreasBergmeier6176 would it work for your use case?

Should work out.

[RomanHotsiy]

PR created https://github.com/Redocly/redocly-cli/pull/2133