Why does basePath must match the yaml file name?

[oswaldo]

broken-example2.yaml.zip

I've done a couple of experiments and noticed that if the basePath doesn't match the yaml file name, I would get a 404 with the requested path as the response body and no other error message to tell me what happened.

As some swagger examples (on swagger's site) show v1 as a basePath, possibly people that follow this approach will trip over the same difficulty.

I confirmed it by creating a simple file based on the example.yaml leaving only the getUserTodos. If you don't set the basePath to /example2, instead of the expected code from the default NotImplementedYet, you should get a 404.

The same is true if you change the basePath to /example2/v1.

I believe that if this is an intentional limitation, it should be documented in the README.md. If not intentional, it is a bug.

The workaround is instead of having a basePath /example2/v1 and a path /todos/{user_id}, having the basePath /example2 and every path prefixed like /v1/todos/{user_id} (which really makes me feel it is a bug as the editor page gets rendered for both, having the operation to point to /example2/v1/todos/{user_id} in both cases)

(moved from zalando-stups/api-first-hand-service#9)

[slavaschmidt]

@oswaldo The base path only needs to match the specification name in the case it is not properly defined in the specification itself. The problem is that it is possible to have multiple specifications at the time and couple of them could define same urls. So we need a kind of namespace for each spec.

We'll improve the documentation.