swagger ui not working when using basepath link is broken

[david-sw]

Description / Steps to reproduce / Feature proposal

in file src/application.ts
i added to the contractor

this.basePath('/icontrol/v1');

so that all controllers will have the base path of /icontrol/v1

Current Behavior

after opening the swagger ui and clicking on the explorer the wrong link is opened
https://explorer.loopback.io/?url=https://127.0.0.1:5443/icontrol/v1/openapi.json
the file openapi.json is not under the new path and if i change the path manually to
https://explorer.loopback.io/?url=https://127.0.0.1:5443/openapi.json
it start working

Expected Behavior

swagger ui link will not change on the static open-api .json

[bajtos]

Possibly related: #2285

after opening the swagger ui and clicking on the explorer the wrong link is opened
https://explorer.loopback.io/?url=https://127.0.0.1:5443/icontrol/v1/openapi.json
the file openapi.json is not under the new path and if i change the path manually to
https://explorer.loopback.io/?url=https://127.0.0.1:5443/openapi.json

IIUC, you have configured basePath as /icontrol/v1, the swagger ui expects the OpenAPI spec to be available at /icontrol/v1/openapi.json but the current implementation is mounting the routes at /openapi.json.

Is that correct description? Based on the source code, I think the actual behavior is opposite: Explorer expects OpenAPI spec to be available at /openapi.json but in fact it's exposed at /${basePath}/openapi.json.

IMO, this is the intended behavior we should eventually get to:

• basePath controls the URL of OpenAPI spec endpoints.
• REST API Explorer is aware of basePath.

I think we need to fix REST API Explorer to take basePath into account when building the spec url here:

https://github.com/strongloop/loopback-next/blob/b5f12be7c2f1f809360122ca72a3e55c5ef92bcb/packages/rest-explorer/src/rest-explorer.controller.ts#L51-L58

Please read through the discussion in #2285 (comment) too, it contains important information relevant to this issue too.

[ghost]

@bajtos @raymondfeng
i am aware this not possible solution for this issue ,
getOpenApiSpecUrl method that you mentioned before is only available when the self hosted explorer enabled

I think we need to fix REST API Explorer to take basePath into account when building the spec url here:
https://github.com/strongloop/loopback-next/blob/b5f12be7c2f1f809360122ca72a3e55c5ef92bcb/packages/rest-explorer/src/rest-explorer.controller.ts#L51-L58

I've checked the following scenarios :

let config = {
                apiExplorer:{disable:true} 
      } ;
let app = new RestApplication(config);
app.basePath('/api')

using the above example the self hosted explorer enabled , so when request the explorer with the base path it will work as expected e.g 127.0.0.1:3000/api/explorer .
the reason why its work cause the self hosted api inject the openapi.json path without the base path inside the htmls pages so when request the explorer using the browser it will open it with out any error .

now if you gonna change this

https://github.com/strongloop/loopback-next/blob/b5f12be7c2f1f809360122ca72a3e55c5ef92bcb/packages/rest-explorer/src/rest-explorer.controller.ts#L57

to

let finalPath =  endpoint || '/openapi.json';
return config.basePath + finalPath ; // e.g basePath/openapi.json 

this will make us struggling the same issue that we now facing in the external explorer .

now lets assume i done the following :

let config = {
                apiExplorer:{disable:false} 
      } ;
let app = new RestApplication(config);
app.basePath('/api')

using this kind of configuration tell lb4 that need to use external lb4 explorer .

https://github.com/strongloop/loopback-next/blob/b5f12be7c2f1f809360122ca72a3e55c5ef92bcb/packages/rest/src/rest.server.ts#L466

now request the explorer with the base path will through a new error that the openapi.json not mounted to the correct path e.g 127.0.0.1:3000/api/explorer will return a json not found ,
cause the external explorer is looking for the openapi.json at the wrong path .

eventually to solve this issue you have a two options :

1. mount the openapi.json with the base path e.g
   127.0.0.1:3000/basePath/openapi.json instead of 127.0.0.1:3000/openapi.json ,
   for me this a bad option, openapi holding a multi server as will lb4 .

    servers:
      - url: https://api.example.com/v1
        description: Production server (uses live data)
      - url: https://api.example.com/sand/box
        description: Sandbox server (uses test data)

2. fix the construction of external explorer path and exclude the base path . and for me its the optimal solution.

this.basePath should be removed when the _redirectToSwaggerUI ask for the path .
https://github.com/strongloop/loopback-next/blob/b5f12be7c2f1f809360122ca72a3e55c5ef92bcb/packages/rest/src/rest.server.ts#L456

[bajtos]

mount the openapi.json with the base path e.g
127.0.0.1:3000/basePath/openapi.json instead of 127.0.0.1:3000/openapi.json

I don't have a strong opinion on what's the "right" path where to expose /openapi.json endpoints. Changing that path would be a breaking change though.

fix the construction of external explorer path and exclude the base path

I agree this is a fix we should make, preferably soon.

[dkrantsberg]

Created a PR to address this issue. It makes /openapi.json and /explorer routes be served relative to basePath.
#2554

[bajtos]

Closing as fixed via #2856