Swagger Updates Breaks API Usage - node.js

Question

My API seems to no longer parse properly using swagger-parser and swagger-tools latest versions after we did a full npm update on all our deps last night. However, I cannot track down what is causing these failures to happen since the API follows proper formatting for the 2.0 spec according to the docs.
Some information on the current setup:
swagger-parser: v3.3.0
swagger-tools: v0.9.7
node: v4.2.1
npm: v2.14.7
We are making use of swagger-tools connect middleware to create a stand-alone API app. Our setup for the api looks like this:
var app = require('connect')();
var cors = require('cors');
var swaggerTools = require('swagger-tools');
var swaggerParser = require('swagger-parser');
app.use(cors());
app.initialize = function (done) {
swaggerParser.parse('./api/swagger.yaml', function (err, api) {
if (err) throw err;
swaggerTools.initializeMiddleware(api, function (middleware) {
app.use(middleware.swaggerMetadata());
app.use(middleware.swaggerValidator());
var options = {
controllers: './controllers',
useStubs: process.env.NODE_ENV === 'development' ? true : false
};
app.use(middleware.swaggerRouter(options));
app.use(middleware.swaggerUi());
typeof done === 'function' && done();
});
});
return app;
};
Prior to the updates on the deps everything worked fine like this. However, now when being initialized our API is throwing a bunch of errors when swaggerTools.initializeMiddleware is being called.
A few chunks of our API are as follows:
./api/swagger.yaml
swagger: '2.0'
info:
version: 0.0.1
title: Insert API Title Here
schemes:
- http
basePath: /api/v1
consumes:
- application/json
produces:
- application/json
paths:
/users:
$ref: './api/paths/users.yaml'
/users/{userId}:
$ref: './api/paths/users-userId.yaml'
definitions:
User:
$ref: './api/models/user.yaml'
parameters:
userId:
in: path
name: userId
description: The user id of the user object.
required: true
type: integer
offset:
name: offset
in: query
description: The record to start the return set at.
required: false
type: integer
default: 0
minimum: 0
limit:
name: limit
in: query
description: The quota to limit the return set to.
required: false
type: integer
default: 10
orderBy:
name: orderBy
in: query
description: The field to order by.
required: false
type: string
sort:
name: sort
in: query
description: The sort order of the return set.
required: false
type: string
enum: [desc, asc]
default: asc
./api/paths/users.yaml
x-swagger-router-controller: Users
get:
tags:
- users
summary: Gets a list of all users.
description: ''
operationId: getUsers
parameters:
- $ref: '#/parameters/offset'
- $ref: '#/parameters/limit'
- $ref: '#/parameters/orderBy'
- $ref: '#/parameters/sort'
responses:
200:
description: OK
schema:
$ref: '#/definitions/UserCollection'
401:
description: Not Authorized
The errors we are seeing are things like this now:
#/paths/~1users/get/parameters/1/name: Parameter already defined: undefined
#/paths/~1users/get/parameters/2/name: Parameter already defined: undefined
#/paths/~1users/get/parameters/3/name: Parameter already defined: undefined
#/paths/~1users~1{userId}/get: API requires path parameter but it is not defined: userId
#/paths/~1users~1{userId}/put/parameters/1/name: Parameter already defined: undefined
#/paths/~1users~1{userId}/put: API requires path parameter but it is not defined: userId
#/paths/~1users~1{userId}/delete: API requires path parameter but it is not defined: userId
#/paths/~1users~1{userId}~1profile/get: API requires path parameter but it is not defined: userId
#/paths/~1users~1{userId}~1profile/post/parameters/1/name: Parameter already defined: undefined
#/paths/~1users~1{userId}~1profile/post: API requires path parameter but it is not defined: userId
I'm not sure where to go from here since I have tried everything to keep the API layout the same (broken into multiple files) vs. having to resort to putting it all into a single file. Our API is rather large and it is much easier to maintain broken into parts like this which used to work fine without issue.
Is there something I am missing, a step that needs to be done differently with the updates to swagger-parser and swagger-tools? Any help is appreciated.

Answer 1

It seems the jump between v2 to v3 of Swagger-Parser has changed the functionality of .parse() to no longer resolve references. Because of this it was causing portions of the API to not validate properly. Switching to .validate() instead of .parse() has fixed this issue. A handful of adjustments had to be made to the .yaml files to make it work with the new 2.0 standards but all is working again.