Swagger更新中斷API使用

Question

在昨晚對所有部門進行了完整的npm更新之后，我的API似乎不再使用swagger-parser和swagger-tools最新版本進行正確的解析。 但是，根據該文檔，API遵循2.0規范的正確格式，因此我無法跟蹤導致這些失敗的原因。

有關當前設置的一些信息：

• swagger-parser：v3.3.0
• 招搖工具：v0.9.7
• 節點：v4.2.1
• npm：v2.14.7

我們正在使用swagger-tools連接中間件來創建獨立的API應用程序。 我們的api設置如下所示：

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;
};

在更新部門之前，一切都可以像這樣正常工作。 但是，現在在初始化時，調用swaggerTools.initializeMiddleware時，我們的API會引發很多錯誤。

我們的API的一些塊如下：

./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

我們現在看到的錯誤是這樣的：

#/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

我不確定從這里開始應該走什么路，因為我已經盡一切努力使API布局保持相同（分為多個文件），而不得不將其全部放入一個文件中。 我們的API相當大，維護成這樣的部件變得容易得多，這些部件過去可以正常工作而不會出現問題。

我缺少什么嗎，需要對swagger-parser和swagger-tools進行更新以不同的方式進行？ 任何幫助表示贊賞。

Answer 1

似乎Swagger-Parser的v2到v3之間的跳轉已更改了.parse（）的功能以不再解析引用。 因此，這導致API的某些部分無法正確驗證。 切換到.validate（）而不是.parse（）可以解決此問題。 必須對.yaml文件進行一些調整，才能使其與新的2.0標准兼容，但所有這些都可以再次使用。