Swagger 更新中断 API 用法

Question

我的 API 似乎不再使用最新版本的 swagger-parser 和 swagger-tools 正确解析，昨晚我们对所有部门进行了完整的 npm 更新。但是，我无法追踪导致这些故障发生的原因，因为 API 根据文档遵循 2.0 规范的正确格式。

关于当前设置的一些信息：

招摇解析器：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;
};

在 deps 更新之前，一切都像这样正常工作。但是，现在初始化时我们的 API 在调用 swaggerTools.initializeMiddleware 时抛出一堆错误。

我们 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 标准，但一切又恢复正常了。

Swagger 更新中断 API 用法

Swagger Updates Breaks API Usage

node.js

api

swagger

swagger-2.0