Problem with path

[mangvlad]

I am trying to use new descPath option and it is not working correctly.

The problem appears to be with routes for operatons.
The code makes all routes to be exactly what "path" attribute is, without using the base path. The UI appends the path to the base path so no operation can be reached.

Also, if you try to get JSON definition, the UI will have something like: http://localhost:8002/api1/v1/api1/v1/api-docs/api1

(Ideally I would like to have several different APIs to be described in the same application and avoid hardcoding "http" and "localhost" as much as possible by using the relative path...)

Here is the sample (docs folder has swagger-ui):

var express = require("express"),
swagger = require("swagger-jack");

var app = express();

app.configure(function () {

    app.use(swagger.generator(app,
        {
            "apiVersion": "0.1",
            "swaggerVersion": "1.1",
            "basePath": "http://localhost:8002/api1/v1",
            "apis": [
                {
                    "path": "",
                    "description": "API 1 Operations"
                }
            ]
        },
            [
        {
            api: {
                "apiVersion": "0.1",
                "swaggerVersion": "1.1",
                "basePath": "http://localhost:8002/api1/v1",
                "resourcePath": "/api1",
                "apis": [
                    {
                        "path": "/operation1",
                        "description": "API 1 related operations",
                        "operations": [
                            {
                                "parameters": [

                                ],
                                "httpMethod": "GET",
                                "notes": "GET",
                                "errorResponses": [
                                ],
                                "nickname": "operation1",
                                "summary": "API 1 Operation1.",
                                "responseClass": ""
                            }
                        ]
                    }
                ],
                "models": {
                }
            },
            controller: {operation1: function getToken(req, res, next) {
                console.log("operation1");
                res.send();
            }
            }
        }
            ],
        {descPath: '/api1/v1/api-docs'}
    )
    );

}

);

var docs_handler = express.static(__dirname + '/docs');
app.get(/^/docs(/.*)?$/, function (req, res, next) {
if (req.url === '/docs') { // express static barfs on root url w/o trailing slash
res.writeHead(302, { 'Location': req.url + '/' });
res.end();
return;
}
// take off leading /docs so that connect locates file correctly
req.url = req.url.substr('/docs'.length);
console.log(req.url)
return docs_handler(req, res, next);
});
// start the server
app.listen(8002);

[mangvlad]

I also have tried using express subpath:

var subpath = express();
app.use("/v1", subpath);
subpath.use(swagger.generator(app...

but getting the same result: operation1's route is still "/operation1"; changing it to "/v1/operaton1" makes UI to want to use "/v1/v1/operaton1"...

[feugy]

Hi Mangvlad.

Tomorrow I'll try to reproduce your problem.
But I can already point some limitations :

1. first, express's mount path is not properly supported. It's clearly a bug, but I currently ignore if it can be fixed, because express doesn't let your middleware know that he's mounted or not on a path. Which is crucial to
   Swagger-jack middlewares
2. your basePath (the one at highest level) is exactly what you want: it's not used by the middleware, but it's a prefix used by swagger-UI before the individual api paths. So it's up to you to make a relative path, hardcoded or not. It depends on where you're serving the swagger-UI files.
3. as far as I know, you don't need to repeat the apiVersion, basePath and swaggerVersion inside the Resource descriptors (below the api property).

Stay tuned !

[mangvlad]

1. If there was another way to do subpath, outside of express it will be ok for my use case. I was only trying it as a way to make it work somehow...
2. I trying to serve UI, specs and controllers for the same express app.
3. According to this https://github.com/wordnik/swagger-core/wiki/API-Declaration both API-Declaration and Resource Listing files expected to have apiVersion, basePath and swaggerVersion... Not sure how it is used, but I guess it should allow for different APIs to be versioned indecently:

Let's say I have security/getprofile and security/gettoken and data/resource1 and data/resource2 operations in 2 different APIs. I would like to expose it to the client like this:

1. security/v1/getprofile and security/v1/gettoken
2. data/v2/resource1 and data/v2/resource2

and in the same time, Resource Listing file can be exposed at my company/api-docs...

[feugy]

Hi Mangvlad.

We fixed this issue in version 1.5.0 (release in progress).
Now the "path" part of the basePath url (anything that is not protocol, host and port) is used as prefix of your resources path, and swagger descriptor.

It will allow you to achieve your goal. On behalf of the team, I apologize for taking so long to handle this problem.

Damien.