While resolving remote or relative references, json-refs does not do a complete resolve.

[amarzavery]

For example: I have two swagger specs A and B residing at the same location.
In the following situation, it will correctly resolve a1 with the B1 from the definitions section of B.json. However, it will not resolve B2 (basically it will not traverse further to ensure that all the other locally referenced properties of that model are also fully resolved).

• A.json

{
. . .
  "definitions": {
     "A1": {
        "properties: {
            "a1": { "$ref": "./B.json#/definitions/B1" }
        }
     }
  }
}

• B.json

{
. . .
  "definitions": {
     "B1": {
        "properties: {
            "b1": { "$ref": "#/definitions/B2" }
        }
     },
     "B2": {
        "properties: {
            "b2": { "type": "string" }
        }
     }
  }
}

Please execute the following example to get an idea.

json-refs resolve  https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/arm-network/2016-09-01/swagger/vmssNetworkInterface.json --filter relative --filter remote

The output swagger will have "$ref": "#/definitions/NetworkInterfacePropertiesFormat" as a reference but there is no definitions section in the output swagger.

Couple of questions:
Btw, I need to do this because swagger-tools does not accept a swagger spec that contains a relative or remote file reference. Hence, I need to resolve them first and then validate the spec.

1. Is it possible for swagger-tools to handle file references (relative or remote) then it will help us tremendously.

2. Does sway handle remote or relative file references in a swagger spec?

Once again, thank you for all the quick responses and genuinely all the tools that you are developing in the swagger space are very very useful 👍

[whitlockjc]

json-refs help resolve says -I, --filter <type> The type of JSON References to resolved. This means that if you run it the way you mentioned above, you would only resolve relative and remote references. But there is a bug (#30) that could explain the issue where you point to a local reference in a remote document and it does not full resolve.

As for swagger-tools supporting relative references, that's one of the many reasons sway came to be. It would be extremely difficult to make swagger-tools' API support relative references. I'm not saying impossible but with swagger-tools being deprecated, I don't see it happening.

Sway does handle all kinds of references.

[amarzavery]

One thing that I miss in Sway after using swagger-tools, is an api to validate a model definition against a given example or sample data.
In swagger-tools, one can simply do:

swt.validateModel(swaggerSpecInJson, modelReference, sampleData, callback);

After looking at the sway api documented over here, I cannot find something like that.

I do see validateRequest() and validateResponse(), however the API forces me to provide some kind of a request and serverResponseWrapper object respectively.
It takes away the simplicity of validating a sample for a request body parameter or a sample of a response body that swagger-tools provides.

Is it possible to expose an api similar to validateModel in Sway as well, in addition to the current validateRequest and validateResponse ?

[whitlockjc]

Well, you can do that with Sway but it's built into it's object model. So if the modelReference in your case corresponded with a parameter or response, you could do the same. Here are some of the APIs:

• Operation#validateRequest
• Operation#validateResponse
• Parameter#getValue (the ParameterValue has an accessor that validates)
• Response#validateResponse

The only reason validateModel was ever expose was to originally use it in the swagger-tools middleware but since it validates the document and then validates the model, it was too slow. This is why the middleware doesn't use this approach anymore.

Also, as for the request/response validation requiring objects/wrappers, it's a very simple wrapper. If you must use something similar to validateModel that can't be achieved via Parameter#getValue(), you could always use lib/helpers.js#validateAgainstSchema which is what is used by all parts of Sway's validation. It's basically the same approach swagger-tools middleware validation worked, but better.

[whitlockjc]

Also, I'm just telling you how/why things are now. I'm all ears if there is a better way. As for the API, I wanted it to be intuitive and to match Swagger objects. I didn't want to create an object for every type because it just didn't make sense. From a model perspective, models are used as responses and inputs via parameter bodies. That's why there are validations for those as they are.

Feel free to make requests in Sway if you need something. Other than that, I'm closing this because the issue you originally filed is a duplicate of #30.