Question

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

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

swagger-parser：v3.3.0
swagger-tools：v0.9.7
node：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 /路径/ 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使用

1 个答案: