Swagger using base path for resource definition

[krukgit]

I'm serving my API from localhost:3000/api/. I keep swagger resources' definition at localhost:3000/docs/swagger/ and I want to serve the documentation from localhost:3000/docs.

I pointed swagger to the root resource definition file (http://localhost:3000/docs/swagger/api-docs.json). File content:

{
  "apiVersion": "2.0",
  "swaggerVersion": "1.2",
  "basePath": "http://localhost:3000/",
  "apis": [
    {
      "path": "api/v2/registrations.{format}",
      "description": "Creating and retrieving a user"
    }
  ]
}

Swagger correctly reads the file and displays registrations resource, however when it tries to fetch the resource specification, instead of using relative path and going to http://localhost:3000/docs/swagger/api/v2/registrations.json it uses api base path, which results in the error:

Unable to read api 'registrations' from path http://localhost:3000/api/v2/registrations.json (server returned undefined)

I traced the error to this line.

What am I doing wrong here?

I fixed it temporarily by changing the basePath in swagger.js:

@@ -171,13 +171,7 @@ SwaggerApi.prototype.buildFromSpec = function(response) {
       }
     }
   }
-  if (response.basePath) {
-    this.basePath = response.basePath;
-  } else if (this.url.indexOf('?') > 0) {
-    this.basePath = this.url.substring(0, this.url.lastIndexOf('?'));
-  } else {
-    this.basePath = this.url;
-  }
+  this.basePath = this.url.substr(0,this.url.lastIndexOf('/')+1);
   if (isApi) {
     var newName = response.resourcePath.replace(/\//g, '');
     this.resourcePath = response.resourcePath;

[fehguy]

Hi, are you using grape-swagger by chance?

[krukgit]

I'm using swagger-docs.

[webron]

While there may still be a bug in swagger-ui, your api-docs.json is wrong as it shouldn't include the basePath property in it (it's not in accordance to the spec). Can you try removing it and test again?

[krukgit]

It's somehow better, but still not fully correct:

Unable to read api 'registrations' from path http://localhost:3000/docs/swagger/api-docs.jsonapi/v2/registrations.json (server returned undefined)

Works with this modification:

    if (response.basePath) {
        this.basePath = response.basePath;
+   } else if (this.url.indexOf('/') > 0) {
+       this.basePath = this.url.substring(0, this.url.lastIndexOf('/')+1);
    } else if (this.url.indexOf('?') > 0) {
        this.basePath = this.url.substring(0, this.url.lastIndexOf('?'));
    } else {
        this.basePath = this.url;
    }

[webron]

"apis": [
{
"path": "api/v2/registrations.{format}",
"description": "Creating and retrieving a user"
}
]

The path should be

  "path": "api/v2/registrations.json",

On 11 July 2014 13:02, Maciej Kruk [email protected] wrote:

It's somehow better, but still not fully correct:

Unable to read api 'registrations' from path http://localhost:3000/docs/swagger/api-docs.jsonapi/v2/registrations.json (server returned undefined)

Works with this modification:

if (response.basePath) {
    this.basePath = response.basePath;

• } else if (this.url.indexOf('/') > 0) {

•   this.basePath = this.url.substring(0, this.url.lastIndexOf('/')+1);
  

  } else if (this.url.indexOf('?') > 0) {
  this.basePath = this.url.substring(0, this.url.lastIndexOf('?'));
  } else {
  this.basePath = this.url;
  }

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

[krukgit]

Changing {format} to json doesn't change anything. swagger.js takes care of it.

[webron]

right, you're missing a leading slash to the value -

  "path": "/api/v2/registrations.{format}",

On 11 July 2014 13:08, Maciej Kruk [email protected] wrote:

Changing {format} to json doesn't change anything. swagger.js takes care
of it.

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

[fehguy]

Hi, I'm going to close this out, please reopen if still an issue.

[bkakadiya42]

on hitting https://api.company.com/api/doc, it gives me:

{
  "apiVersion": "v1",
  "swaggerVersion": "1.2",
  "produces": [
    "application/json"
  ],
  "operations": [],
  "apis": [
    {
      "path": "/api/doc/users.{format}"
    }
  ],
  "info": {},
  "basePath": "https://api.company.com"
}

on using swagger-codegen for ruby, it gives me:
base path is https://api.company.com/api/doc
java.io.FileNotFoundException: https://api.company.com/api/doc/api/doc/users.json

however api's(calls to https://api.company.com/v1/users etc) are working correctly as expected.
not sure if this is issue with swagger ui or swagger client lib generator.

[webron]

@kakadiya91 - The output:

{
  "apiVersion": "v1",
  "swaggerVersion": "1.2",
  "produces": [
    "application/json"
  ],
  "operations": [],
  "apis": [
    {
      "path": "/api/doc/users.{format}"
    }
  ],
  "info": {},
  "basePath": "https://api.company.com"
}

is incorrect - this is an invalid swagger specification file. The ui may work properly, but the codegen may be a bit more sensitive to malformed structures.

[fehguy]

@kakadiya91 are you using grape swagger by chance? If so there's a fork that addresses these issues, see this sample:

https://github.com/wordnik/rails-petstore

[bkakadiya42]

Thank you @fehguy, @webron. I pointed my app to that gem (https://github.com/CraigCottingham/grape-swagger), made some code changes to my api repo to work with this gem, now it works like a charm.