使用 swagger-ui-express 和 swagger-jsdoc 进行记录时，如何指向 json 文件进行模式定义？

Question

我目前正在使用 ajv 来验证 node/express 中的一些 API 输入。预期数据在 .json 架构文件中描述。

现在我想重新使用这个文件来记录我的 API，依靠 swagger-ui-express 和 swagger-jsdoc。

有很多关于如何在 swagger 中重用对象定义的参考，但所有这些描述都假设定义是在“@swagger”注释块中给出的。

我只是不知道如何指向本地 JSON 文件。

如果我的评论是这样的：

/**
* @swagger
* /init/user:
*   post:
*     description: Creates a user
*     produces:
*       - application/json
*     parameters:
*       - in: body
*         name: create user
*         required: true
*         schema:
*           $ref: 'schemas/initUserApi.json'
*/

（注意这是一个不完整的模板，我想重点解决这个问题），那么最终swagger输出会抛出错误：

Could not resolve reference: Tried to resolve a relative URL, without having a basePath. path: 'schemas/initUserApi.json' basePath: 'undefined'

我尝试定义一个“组件”部分，如本期所述：无法引用 Swagger 中单独文件中定义的组件架构，这没有任何作用。

我尝试使用绝对/相对文件名等（这里还有另一个建议：如何在使用 swagger-ui-express 和 swagger-jsdoc 时正确使用 $ref 在 swagger 文件中），但无济于事。

这可能吗？目标实际上是使用单独的 json 文件作为模式，因为我希望有一个单一的信息源。我不清楚 swagger-ui-express/swagger-jsdoc 链是如何工作的，这个 json 文件是否需要以某种方式由我的 swagger web 服务器提供服务（这实际上是目前在本地主机上运行的文档，没有公共/内联网发布) ?

Answer 1

it\xe2\x80\x99s 有点旧，但对于所有仍在寻找解决方案的人来说，在我看来，这个是有效的。

\n

首先，您必须从 json 文件中导出架构，如下所示：

\n

export const initUserApi = {\n  type: \'object\',\n  properties: {...}\n};\n

\n

然后，在 swagger 配置所在的文件中，您必须将此架构添加到swagger Components内的Schemas中：

\n

/**\n * @swagger\n * infos: ...\n * basepath: ...\n * paths: ...\n * components:\n *   schemas:\n *     initUserApi:\n *       $ref: \'path/to/initUserApi.json\'\n */\n

\n

完成\xe2\x80\x99s 后，您可以将这个新的initUserApi模式与您的路由一起使用，如下所示：

\n

/**\n* @swagger\n* /init/user:\n*   post:\n*     description: Creates a user\n*     produces:\n*       - application/json\n*     parameters:\n*       - in: body\n*         name: create user\n*         required: true\n*         schema:\n*           $ref: \'#/components/schemas/initUserApi\'\n*/\n

\n

但根据您的 swagger/openapi 版本（2.0、3.0.n、3.1 等），此解决方案可能不起作用，因此您可能必须将 JSON 文件转换为 YAML 文件。为此有很多在线转换器，最简单、最方便的是我经常使用的这个： https: //www.json2yaml.com/

\n

然后就应该可以正常工作了。

\n