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

7ajki6be 于 2023-03-23 发布在其他

关注(0)|答案(1)|浏览(184)

我目前正在使用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'
*/

(note这是一个不完整的模板，我想把重点放在问题上），那么最终的swagger输出将抛出一个错误：
Could not resolve reference: Tried to resolve a relative URL, without having a basePath. path: 'schemas/initUserApi.json' basePath: 'undefined'
我尝试定义一个“组件”部分，如本期所述：Cannot reference a component schema defined in a separate file in Swagger，这什么也不做。
我尝试使用绝对/相对文件名等（这里还有另一个建议：How to use $ref in swagger file properly while working with swagger-ui-express and swagger-jsdoc），无济于事。
这是可能的吗？目标是使用一个单独的json文件作为模式，因为我希望有一个单一的信息源。我不清楚swagger-ui-express/swagger-jsdoc链是如何工作的，这个json文件是否需要通过我的swagger web服务器提供服务（目前这是运行在本地主机上的文档，没有公共/内联网发布）？

swagger

来源：https://stackoverflow.com/questions/59616603/when-documenting-with-swagger-ui-express-and-swagger-jsdoc-how-to-point-to-json

1条答案

按热度按时间

jdzmm42g1#

这是一个有点旧，但对于所有那些谁仍然在寻找解决方案，它似乎对我来说，这一个工程。
首先，你必须从你的json文件中导出你的schema如下：

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

然后，在swagger配置所在的文件中，您必须将此模式添加到swaggerComponents中的Schemas中：

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

完成后，您可以将这个新的 initUserApi schema与您的路由一起使用：

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

但是根据你的swagger/openapi版本（2.0，3.0.n，3.1等），这个解决方案可能不起作用，所以你可能需要将JSON文件转换为YAML文件。有很多在线转换器，最简单和最方便的是这个，我经常用途：https://www.json2yaml.com/
它应该正常工作。

赞(0）回复(0）举报 2023-03-23

我来回答

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

1条答案

相关问题

热门标签

最新问答