How should a basePath "/" be interpreted by tooling in OAS2?

[alasdairhurst]

When constructing a URL from a document with a basePath / it's unclear what the expected outcome is.

In the Swagger 2 spec it says that

1. basePath is optional
2. if provided, basePath must begin with /
3. Paths Object keys must begin with / and the path is appended to the basePath in order to construct the full URL.

This suggests the following structure (ignoring scheme for now):
<host><basePath><path>

Without a basePath:

"host": "host.com",
"paths": {
  "/user": {}
}

results in host.com/user

With a basePath:

"host": "host.com",
"basePath": "/api"
"paths": {
  "/user": {}
}

results in host.com/api/user

Finally, following the same logic:

"host": "host.com",
"basePath": "/"
"paths": {
  "/user": {}
}

results in host.com//user

Now, I realise that this isn't the offical spec, but it seems that the expectation isn't 100% clear. swagger.io documentation suggests something else:
https://swagger.io/docs/specification/2-0/api-host-and-base-path/

See

If basePath is not specified, it defaults to /, that is, all paths start at the host root.

This is considering / to be the same as not providing the value which isn't in the original spec.

A number of other tools such as Stoplight are also interpreting / to be the root rather than an explicit basePath, which I think is wrong, and resulting in a lot of bad swaggers in the wild. It's not too bad when you're reading the swagger as documentation and interpreting it yourself, but if you're writing a tool, you need to follow the spec as correctly as possible. In this case it could end up with not calling the correct API, or not showing the correct path as was indended.

The question I have:

1. When concatenating host, basePath and paths, should duplicated slashes be stripped (assuming the document was written haphazardly), or should all slashes be kept literally?

This should probably be clarified so it's not up to interpretation.

[webron]

This is why writing specifications is hard. 😉

This seems more like an edge case that was almost thought through, but wasn't. I'd say it is safe to assume that if the basePath is / only (whether implicitly or explicitly), it can be ignored and the paths are to be appended to the host. Meaning, it will not have // there. That said, I would not go and automatically assume that // should be stripped elsewhere, especially if it's included directly in the paths.

Unfortunately, clarifying it in the specification itself is not an option, since we can't really make any changes to it. 2.0 was not structured in a way we can publish patch releases. However, this discussion will hopefully be able to help additional people in the future.

Of course, if people migrate to newer versions, that would not be an issue at all. And they should. Really. 😄

[alasdairhurst]

Thanks for the quick response.

Agree people should be moving towards newer version, the downside of writing tooling that you want to have wide compatibility is that this stuff needs to be accounted for unfortunately.

Anyway, thanks again for the feedback. we'll decide what to do from here - either stripping basePath entirely if it's /, or leaving the option for the user to configure how it's interpreted.

[handrews]

Seems like this was answered as much as it could be, given the 2.0 limitations (and it's not a problem in 3.x). Closing.