使用 Swagger 的 feathers.js 服务的自定义文档

Question

我已经在我的 Feather.js 应用程序中配置了 Swagger，它会自动为每个服务上的所有端点生成文档。现在，我想省略某些服务上的某些端点作为文档生成，因为我只是不允许这些端点或在它们背后有一些隐藏的逻辑，这不允许external 调用。

F.e.我的/users/me 服务的端点有以下设置：

before: {
    all: [authenticate('jwt')],
    find: [
      /*
       * We don't use an ID when calling `/users/me` like `/users/me/<id>`, and therefore Feathers understands the
       * incoming request as a `find` method instead of `get`, therefore we simply redirect it internally.
       */
      async context => {
        context.result = await context.service.get(context.params.user.id); // eslint-disable-line
        return context;
      }
    ],
    get: [
      iff(isProvider('external'), disallow()),
      includeGender()
    ],
    create: [disallow()],
    update: [setAuthenticatedUserId()],
    patch: [setAuthenticatedUserId()],
    remove: [setAuthenticatedUserId()]
  }

从逻辑设置中可以看出，我希望生成以下文档：

关于feathers-swagger，我已关注these docs。我使用schemasGenerator(service, model, modelName, schemas) 为每个服务生成文档。可以理解，这将为每个服务生成相同的文档模式。根据 github 模块说明，我尝试通过添加 docs 对象来添加自定义内容：

 service.docs = {
            ...service.docs,
            operations: {
              find: false,
              create: false
            }
          };

或在 Swagger 配置中添加一个全局 operations: { find: false, create: false } 对象。

第一个选项没有效果，第二个选项将其应用于所有端点，这对我没有帮助。

Answer 1

您必须使用“忽略”选项来排除您想要的端点。您可以指定 'tags' 数组或 'paths' 数组。

app.configure(swagger({
  docsPath: '/api/docs',
  uiIndex: true,
  specs: {
    info: {
      title: 'API Docs',
      description: 'Rest APIs',
      version: '1.0.0',
    },
    schemes: ['http', 'https'],
  },
  ignore: {
    paths: [
      'users'
    ]
  }
})); 

您也可以从服务级别忽略端点。

usersService.docs = {
    description: 'A service to manage users',
    definitions: {
      users: m2s(options.Model),
      'users_list': {
        type: 'array',
        items: { $ref: '#/definitions/users' }
      }
    },
    securities: ['find', 'get', 'update', 'patch', 'remove'],
    operations: {'create': false}
  };

Get complete documentation for feathers-swagger here