Swagger validation error when running on 0.0.0.0

[strongloop]

Swagger validation error when running on 0.0.0.0

[bajtos]

That's expected, the server running at online.swagger.io cannot access the application running on your local machine.

You can run swagger-badge locally to check your local application, see the instructions in project's README.

[bajtos]

@hacksparrow where is the validator badge coming from? I can't see it in [email protected] installed from npmjs.

[JinpaLhawang]

We've witnessed this in our app since updating from loopback-explorer 1.1.0 to 2.0.0. We don't have a swagger.json file in our project. This error displays in the lower right corner and when clicked it opens http://online.swagger.io/validator/debug?url=http://0.0.0.0:3000/explorer/swagger.json with the response:

[
  {
    level: "error",
    message: "Can't read from file http://0.0.0.0:3000/explorer/swagger.json"
  }
]

I guess swagger.json was not required before and now is?

[bajtos]

@JinpaLhawang do you perhaps provide custom copy of swagger-ui to the loopback-explorer module?

Could you please create a sample project reproducing the problem which I can use to troubleshoot this on my machine? See wiki instructions.

[bajtos]

Never mind, I am able to reproduce this locally too. It's important to use 0.0.0.0 as the hostname. It seems that swagger-ui detects localhost and does not show the badge in such case, but it fails to recognise 0.0.0.0 as a local address too.

[bajtos]

Here is the code detecting validatorUrl: https://github.com/swagger-api/swagger-ui/blob/8e72906c911a02853b87f5241d157e83e2bf7377/src/main/javascript/view/MainView.js#L57-L71

Is there any volunteer to fix the issue and submit a pull request to swagger-ui project?

[raymondfeng]

Please note 0.0.0.0 is not a valid localhost ip on Windows.

[hacksparrow]

Also, a simple check for 0.0.0.0 would not suffice. It should detect any IP address within all the possible private IP blocks - 192.168.0.0-192.168.255.255, 172.16.0.0-172.31.255.255, and 10.0.0.0-10.255.255.255.

[bajtos]

I don't think it's possible to implement a fully bullet-proof check - consider the case when your API is served from an internal host http://intranet/explorer, which is mapped by your on-premise DNS to a private IP address.

Perhaps we could modify loopback-explorer to always pass swaggerOptions.validatorUrl: null and thus always disable the badge?

Optionally we could add loopback-explorer setting to configure the validatorUrl. We are already calling GET /exporer/config.json to fetch some metadata from the server, I think it should be reasonably easy to pass through this new option. See public/lib/loadSwaggerUI.js and index.js

/cc @STRML

[STRML]

Well, if the explorer loads, swagger.json must be reachable from the client. So why don't we just read this error and ignore it by removing the badge?

[bajtos]

@STRML I think this is a different problem - it's about the site online.swagger.io not able to access swagger.json served by the LoopBack app running on your local machine.

[hacksparrow]

I don't think it's possible to implement a fully bullet-proof check - consider the case when your API is served from an internal host http://intranet/explorer, which is mapped by your on-premise DNS to a private IP address.

@bajtos you've got a point there.

Perhaps we could modify loopback-explorer to always pass swaggerOptions.validatorUrl: null and thus always disable the badge?

I think the badge should be enabled only via an explicit config option, not by default.

[STRML]

@bajtos What I mean is, we can't get this validation to work if the swagger.json isn't reachable from the online validation service. So we want to hide the badge if it errors. So let's just specialcase this error.

[bajtos]

@STRML What I mean is, we can't get this validation to work if the swagger.json isn't reachable from the online validation service. So we want to hide the badge if it errors. So let's just specialcase this error.

AFAICT, the badge is implemented as an image fetched from the validation services, so it's not possible to tell why the validation failed:

<a href="http://online.swagger.io/validator/debug?url=http://0.0.0.0:3000/explorer/swagger.json">
  <img id="validator" src="http://online.swagger.io/validator?url=http://0.0.0.0:3000/explorer/swagger.json">
</a>

However, the debug endpoint returns a nice JSON which we could use to check whether swagger.json is reachable.

// http://online.swagger.io/validator/debug?url=http://0.0.0.0:3000/explorer/swagger.json
[{"level":"error","message":"Can't read from file http://0.0.0.0:3000/explorer/swagger.json"}]

There is still a catch though: when running in a corporate environment behind a strict firewall, access to online.swagger.io may be silently rejected via a timeout. In which case it will take us quite some time to finish this check.

Thoughts?

[STRML]

That seems fine. I think the right thing to do is to place the image ourselves by storing the variants locally and displaying it based on a hit to their API, rather than having them handle the image display.

Otherwise, the mechanism you describe will basically double-hit their API (once for the check, once for the image). But I would hope they're caching results.

[hacksparrow]

@bajtos how about we do this?

Perhaps we could modify loopback-explorer to always pass swaggerOptions.validatorUrl: null and thus always disable the badge?

[bajtos]

@bajtos how about we do this?

Perhaps we could modify loopback-explorer to always pass swaggerOptions.validatorUrl: null and thus always disable the badge?

Sounds good to me.

We can always implement a more elaborate solution (e.g. as proposed by @STRML in #120 (comment)) later, when there is a volunteer with enough free time.

[bajtos]

Is there any volunteer willing to contribute the fix outlined in #120 (comment)?

Modify loopback-explorer to always pass swaggerOptions.validatorUrl: null and thus always disable the badge?

[hacksparrow]

@bajtos I'll take it up.

[bajtos]

The fix is available in [email protected]