Algorithm to deduce 'basePath' from Swagger document location.

[IvanGoncharov]

In my scenario host, schemes and basePath.
According to spec there are rules how to deduce host and schemes:

If the host is not included, the host serving the documentation is to be used (including the port).

If the schemes is not included, the default scheme to be used is the one used to access the Swagger definition itself.

But what to do with basePath is unclear, closes thing is:

If it is not included, the API is served directly under the host.

Which is not very suited for situation.

[mohsen1]

When basePath is not present it means all the URLs are relative to host.
When host is not present, current host will be used.

Imagine all following swagger specs are served from http://example.com/swagger

When there is no host, basePath or scheme

swagger: '2.0'
info:
  version: 0.0.0
  title: Simple API
paths:
  /foo:
    get:
      responses: 
        200:
          description: OK

GET /foo → GET http://example.com/foo

When scheme is specified

swagger: '2.0'
schemes:
  - https
info:
  version: 0.0.0
  title: Simple API
paths:
  /foo:
    get:
      responses: 
        200:
          description: OK

GET /foo → GET https://example.com/foo

When basePath is specified

swagger: '2.0'
basePath: /api
info:
  version: 0.0.0
  title: Simple API
paths:
  /foo:
    get:
      responses: 
        200:
          description: OK

GET /foo → GET http://example.com/api/foo

When host is specified

swagger: '2.0'
host: swagger.io
info:
  version: 0.0.0
  title: Simple API
paths:
  /foo:
    get:
      responses: 
        200:
          description: OK

GET /foo → GET http://swagger.io/foo

[IvanGoncharov]

@mohsen1 Thanks for such detailed explanation.
But let's change your example a little bit.
Swagger specification is now served from http://example.com/testing/swagger
And there is no host, basePath or scheme:

swagger: '2.0'
info:
  version: 0.0.0
  title: Simple API
paths:
  /foo:
    get:
      responses: 
        200:
          description: OK

According to current spec:
GET /foo → GET http://example.com/foo
But logically it should be:
GET /foo → GET http://example.com/testing/foo

So basically Swagger provide very good mechanism for deploying APIs without being tied to particular hostname. But at the same time it limits you with one API per host rule.

I understand it's not in scope of 2.0 version.
But it could be solved in next version.

My solution to this, is to deduce basePath similarly to host and schemes:

If the basePath is not included, the path to be used is the one used to access the Swagger definition itself with file name being removed.

During conversion from 2.0, if basePath is missing, empty basePath should be added.

[webron]

@mohsen1's description looks accurate.

@IvanGoncharov - regarding the current version, I tend to disagree. We make no suggestions as to where the swagger definition should be hosted within the server, and whether it is hosted at the root, application context, or some other place entirely is beyond the scope. As such, unlike the scheme and host, we cannot assume the basePath.

For a future version, I agree we can take it under consideration, but I can also see why some may not like it.

[jonocodes]

I agree with the behavior @IvanGoncharov is suggesting.

To reiterate, my API is used internal and external to our network with different paths. Here is how you would get to the same API from different ways.
http://internalroute/swagger.json
http://externalroute/fooapi/swagger.json

@webron , I understand what you are saying about being cautious to make this the default behavior. Perhaps this can be done:

If the spec is configured with no basePath, it can assume '/'.
If the basePath is configured to '', it can try to be relative to the spec output.
In the above example this would mean
http://externalroute/fooapi/swagger.json
would produce a basepath of '/fooapi'

and http://internalroute/swagger.json
would produce a basepath of '/'

I would call this a relative basepath, and for my purposes I would think this should be the default, but it doesnt have to be.

[ralfhandl]

+1: we face the same problem as @IvanGoncharov and need a mechanism to specify the basePath relative to the location of the OpenAPI document. Using an empty string as "next to the document" would work fine for us as OData $metadata is always at the service root == basePath.