Swagger Updates Breaks API Usage

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.