Use Swagger 2.0 API Spec with swagger-node-express

[AbhishekBatwara]

trafficstars

What I found is that npm module version 2.1.3 is using swagger 1.2. Currently I am using 1.2 version of API spec. I want to update that to Swagger 2.0, is that a way I can update my currently running project to use swagger 2.0. is that correct w.r.t. swagger-node on Github branch 2.1.x - swagger 1.2 branch master - swagger 2.0

Any help will be appreciated.

[petermorlion]

I'm not an active contributor on this project, but from what I gather you are correct. Except... Swagger (and OpenAPI) currently seem to take a different approach: you design your API first, using markdown, and then generate code for the endpoints. Then you implement those endpoints. So the master branch works documentation first, whereas the 2.1.x branch worked code-first.

EDIT: As I understand now, there are two approaches: bottom-up (code-first) and top-down (doc-first). Some libraries support bottom-up, but this one is (currently) geared towards top-down.

This means they are incompatible with each other, and there is, AFAIK, no easy way to go from one to the other.

On a side note: I'm also interested in what this means regarding workflow. When an endpoint is added, do you add it to your markdown, regenerate the project and copy it over the existing files?

As a solution, you could use api-spec-converter to convert your Swagger 1.2 docs to Swagger 2 or OpenAPI 3 docs. Assuming you have a Swagger 1.2 endpoint configured at /swagger, you could then do this for another endpoint (e.g. `/swagger2´):

var Converter = require('api-spec-converter');

Converter.convert({
    from: 'swagger_1',
    to: 'swagger_2',
    source: `${process.env.API_HOST}/swagger`,
}, function(err, converted) {
    if (err) {
        next(err);
    } else {
        res.json(converted.spec);
    }
})

And from Swagger 2 to OpenAPI 3 (you can't go directly from 1 to 3):

Converter.convert({
    from: 'swagger_2',
    to: 'openapi_3',
    source: `${process.env.API_HOST}/swagger2`,
}, function(err, converted) {
    if (err) {
        next(err);
    } else {
        res.json(converted.spec);
    }
})

But it's a rather convoluted workaround at best.