Arazzo Runner - Questions about URL configuration

[YOU54F]

Hey hey,

Given the Arazzo runner a spin, it's very nice so far. thanks team!

Couple of usability issues I found with the server urls in an OAD.

My use case is testing a backend api, which may be running on http or https, either locally, or deployed somewhere, so I want to be able to select 1 of multiple server urls defined in an OAD, or overwrite the url completely on the fly (effectively ignoring the server url defined in the OAD), as the url for my deployed service may not be a known url that can be defined in the OAD prior to execution

1. I can only overwrite portions of the url via variables, not the full url (so I cannot change scheme from http / https)

https://github.com/jentic/arazzo-engine/blob/main/runner/README.md#example

2. If there is an array of server urls, there doesn't seem to be an option to use any other url other than the first. If this was available, this would allow me to negate issue one, as I could have two server urls, parameterised, one with a http scheme, one with https.

[char0n]

Hi @YOU54F,

Thank you for your thoughts and for opening this topic.

1. I can only overwrite portions of the url via variables, not the full url (so I cannot change scheme from http / https)

Yes there is no capability to fully override the server URL.

2. If there is an array of server urls, there doesn't seem to be an option to use any other url other than the first. If this was available, this would allow me to negate issue one, as I could have two server urls, parameterised, one with a http scheme, one with https.

Yes, as you mentioned, it only goes for first server url and tries to apply server variables to it.

---

IMHO one way forward would be to provide a new --server-url option. When there are more OpenAPI sources within Arazzo Document, --server-url <source-name>=<url> mapping MUST be used. This new option would expect one of the following:

1. Concrete non-relative URL (absolute URL)
2. URL relative reference
3. Server URL template

concrete non-relative URL (absolute URL)

When non-relative URL is detected, it's used as is and completely overrides all defined Server Object in OpenAPI Description.

URL relative reference

It will try to match one of the Server Object present in OpenAPI.servers fixed field. If not matched it would raise error. If matched it must be resolved against the OpenAPI Document retrievalURI.

Server URL template

It will try to match one of the Server Object present in OpenAPI.servers fixed fields. If not matched it would raise error. If matched, server url template is resolved and if resolution produces relative reference, it must be resolved against the OpenAPI Document retrievalURI.

---

There are further complications - every OpenAPI Path Item and Operation objects can have it's own servers fixed field associated with it - this field overrides the top level OpenAPI.servers or Path Item.servers respectively. If we allow --server-url option to completely override OpenAPI servers, we might end up with only partially working API as some path items or operations are expecting a different server.

I think in first phase, we can just introduce support for --server-url with concrete non-relative URL that does override everything. It should covers the major use-case.