Service that exposes resource named "api"

[nunogoncalves]

Hello,

I'm having a hard time trying to figure this out. We have a service which serves a resource name called "api".

Here's the json:

{
  "apiVersion": "v0",
  "swaggerVersion": "1.2",
  "produces": [
    "application/json"
  ],
  "apis": [
    {
      "path": "/apis",
      "description": "Operations about apis"
    }
  ],
  "info": { }
}

When calling the /apis I get the following json: (simplified)

{
  "apiVersion": "v0",
  "swaggerVersion": "1.2",
  "resourcePath": "/apis",
  "produces": [
  "application/json"
  ],
  "apis": [
  {
    "path": "/v0/apis",
    "operations": [
      {
        "notes": "",
        "summary": "Get all apis",
        "nickname": "GET--version-apis",
        "method": "GET",
        "parameters": [ { ... } ],
        "type": "Apis::Index",
        "responseMessages": [
          {
            "code": 200,
            "message": "Ok"
          }
        ]
      }
    ],
  "basePath": "http://localhost:3011",
  "models": {
    "Apis::Index": {
      "id": "Apis::Index",
      "properties": { }
    }, ...
  }
}

And when swagger-ui builds the html, the

is empty:



---

If I change the name of the resource, say to apis, then I get proper endpoints built.


I was trying to dig into the code, but I find it very hard, so I decided to come here asking for help.

I guess it has something to do with these lines in swagger.js file. When I have the resource name api, it never gets "ready" and always exits the method in the resource.ready == null condition.

SwaggerApi.prototype.selfReflect = function() {
      var resource, resource_name, _ref;
      if (this.apis == null) {
        return false;
      }
      _ref = this.apis;
      for (resource_name in _ref) {
        resource = _ref[resource_name];
        if (resource.ready == null) {
          return false;
        }
      }
      this.setConsolidatedModels();
      this.ready = true;
      if (this.success != null) {
        return this.success();
      }
    };

Thank you in advance.

[webron]

@nunogoncalves - I was sure we solved the issue with apis, however, it may be related to you using Swagger 1.2.

Which version of swagger-ui do you use? Have you tried the latest master with it?

[nunogoncalves]

@webron My swagger-ui.js doesn't seem to have a version on it.
I'll check with the newer version to see if the bug goes away and let you know. :)

[webron]

@nunogoncalves - did you get a chance to check?

[nunogoncalves]

Sorry, not yet. I had a weekly commitment I had to stick to and couldn't
yet. If you prefer we can close this and if I see the problem remains I'll
reopen it. Ok?

No dia quinta-feira, 28 de maio de 2015, Ron [email protected]
escreveu:

@nunogoncalves https://github.com/nunogoncalves - did you get a chance
to check?

—
Reply to this email directly or view it on GitHub
#1314 (comment)
.

Cumprimentos,
Nuno Gonçalves

[webron]

We'll leave it open for a few more days, but would appreciate the feedback to see if there's work do be done here.

[nunogoncalves]

Well, I'll definitely do it, because it's part of one of my tasks. :) Might be as late as early next week. :) Sorry for the delay though.

[nunogoncalves]

Hi! I think I got it! I refreshed the whole JS folder to use the new Swagger-UI and this issue is now working.

However, I'm hitting on two new problems:

I'm getting a warning about the api which exposes "api" resource

spec-converter.js:203 The 'apis' tag conflicts with a SwaggerClient function/property name. Use 'client._apis' or 'client.apis.apis' instead of 'client.apis'.

I don't really know what I should do when the warning states use 'client._apis'... should I actually change the swagger-ui.js code?

And second, our apis, use JWT authentication, and I'm trying to add the auth token in the request, but I'm facing problems:

• if I do it this way (the old way):

window.authorizations.add( 'api_key', new ApiKeyAuthorization('authorization', data.token, 'header'));

I get warnings:

window.ApiKeyAuthorization is deprecated. Please use SwaggerClient.ApiKeyAuthorization.
index.js:24Using window.authorizations is deprecated. Please use SwaggerUi.api.clientAuthorizations.add().

• If I use

swaggerUi.api.clientAuthorizations.add("key", new SwaggerClient.ApiKeyAuthorization("Authorization", "XXXX", "header"));

Then I get

Uncaught TypeError: Cannot read property 'clientAuthorizations' of null (swagger-ui.js:20673)

swaggerUI exists, but api is null... this is for any API, not just the api which exposes a resource called api. :)

Sorry for the trouble. :)

[ponelat]

Hey @nunogoncalves,

Lets see if we can clear things up...

---

• swagger-js uses apis, which is why its warning you. However swagger-ui knows this and should use the safer approach of client.apis.<your tag> which would be client.apis.apis
• If you want to add auth tokens/headers you'll need to do it in the success callback ... here is a gist... https://gist.github.com/ponelat/b2fcea0c7921029d72dc
• If you need the auth tokens/headers to fetch the actual spec file, take a look this issue Authorization for the inital fetching of swagger spec file. swagger-js#445

[nunogoncalves]

Thanks for your answer @ponelat

Indeed I need to add the auth token in every request, including to fetch the spec file.

I'm very confused with all this.

I'm using swagger-ui which, the way I see it, besides providing the ui, hides the swagger-js details. Looking at swagger-ui readme here it says that If I want to add custom headers I can do like so:

swaggerUi.api.clientAuthorizations.add("key", new SwaggerClient.ApiKeyAuthorization("Authorization", "XXXX", "header"));

But doing It trows the error I showed earlier. swaggerUI.api is null so api isn't built at the time. So I guess that for this to work to also fetch the spec file, I have to create the SwaggerClient object, right?

For what I see in the issue your pointed to, I would have to create that SwaggerClient object myself, right? But then I don't know how to make it work with swagger-ui... :/

I have tried something basic

       if (swaggerUi.api === undefined || swaggerUi.api == null) {
          var client = new SwaggerClient({
             authorizations: {  // will become a SwaggerAuthorization object
               api_key: new SwaggerClient.ApiKeyAuthorization("Authorization", "XXXX", "header")
             }
          });
          swaggerUi.api = client
        }

but it'll brake elsewhere saying

this.clientAuthorizations.apply is not a function

[ponelat]

@nunogoncalves ok, if you need to add auth for the spec itself you'll have to wait for the issue above. I'll probably have it done soon, within this week most likely.

You're right about swagger-ui hiding the details of swagger-js. Or more specifically, it simply uses swagger-js for its purposes. It also exposes the swagger-js instance as swaggerUi.api

The reason you're getting that error, is because we can only rely on swaggerUi.api being instantiated in the success callback in the options when we create swaggerUi. Otherwise it is null

[nunogoncalves]

Hi @ponelat .

Maybe I should consider opening a new issue with this, but I'll post it here anyway. If it's better to open a new one, I'll do it.

I just updated the swagger-ui (which if I'm not mistaken includes the updated version of swagger-js as well) and my preivous issues are fixed. I now can authenticate my requests, including the spec file request.

Now another problem issue arouse.

I'm having an error on swagger-ui.js (line 2363)

Resolver.prototype.resolveAllOf = function(spec, obj, depth) {
  depth = depth || 0;
  obj = obj || spec;
  var name;

Uncaught RangeError: Maximum call stack size exceeded

So the resolveAllOf method it's being called indefinitely and throws the error.

Since this happened with APIs that were already closed, I started triming down code to see where the problem was coming from.
Turns out comes from the model having a field "required: null", ....

If I remove this required, then it works.

Before posting the examples, can you tell me if the behaviour is intended? Because if it's not, I must then fill an issue with the owner of swagger-docs, which I'm building my rails swagger docs with. I tried in there to remove this property with no effect.

I'll paste here two examples. One working and one broken.

Working example:

{
  "apiVersion": "0",
  "swaggerVersion": "1.2",
  "basePath": "http://localhost:3000/",
  "resourcePath": "dogs",
  "apis": [
    {
      "path": "v0/dogs/{id}/notes.json",
      "operations": [
        {
          "summary": "Update dog notes",
          "notes": "Update dog notes",
          "parameters": [
            {
              "paramType": "body",
              "name": "dog",
              "type": "notes",
              "description": null,
              "required": false
            }
          ],
          "method": "put",
          "nickname": "V0::Dogs#update_dog_notes"
        }
      ]
    }
  ],
  "models": {
    "dog": {
      "id": "dog",
      "required": "foo",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Dog notes"
        }
      }
    }
  }
}

{
  "apiVersion": "0",
  "swaggerVersion": "1.2",
  "basePath": "http://localhost:3000/",
  "resourcePath": "dogs",
  "apis": [
    {
      "path": "v0/dogs/{id}/notes.json",
      "operations": [
        {
          "summary": "Update dog notes",
          "notes": "Update dog notes",
          "parameters": [
            {
              "paramType": "body",
              "name": "dog",
              "type": "notes",
              "description": null,
              "required": false
            }
          ],
          "method": "put",
          "nickname": "V0::Dogs#update_dog_notes"
        }
      ]
    }
  ],
  "models": {
    "dog": {
      "id": "dog",
      "required": null,
      "properties": {
        "id": {
          "type": "integer",
          "description": "Dog notes"
        }
      }
    }
  }
}

[webron]

@nunogoncalves - Since you say the original issue is resolved, I'll close this one. In general, yeah, it's better to open a different issue. However, I can tell you that "required": null is indeed not valid and should be fixed by the producer.

[ponelat]

@nunogoncalves thanks for the above specs, they'll definitely help! Copy/paste will be fine for the new issue.