node.js - 如何在使用 swagger-ui-express 和 swagger-jsdoc 时正确使用 swagger 文件中的 $ref

Question

我开始在 上使用 swagger swagger-ui-express 和 swagger-jsdoc 自动记录我现有的 API，它是用 nodejs 和 express 编写的(就像这里描述的 - example)。

我在尝试添加 $ref 时遇到了问题到我的注释上的现有 JSON 模式文件(位于我的项目中，与我的所有 js 文件位于同一目录中)。

My directory looks like this

我尝试写本地路径( ./schema.json )和绝对路径，尝试使用 # ，使用了许多语法，但没有任何效果。

我的注释是这样的:

/**
 * @swagger
 * /testing:
 *    get:
 *      description: This should show the json schema
 *      responses:
 *          200:
 *              description: "successful operation"
 *              schema:
 *                 $ref: "./schema.json"
 */

我希望 swagger ui 在我的请求部分向我显示 JSON 模式。我收到以下错误 -

Resolver error at paths./testing.get.responses.200.schema.$ref
Could not resolve reference: Tried to resolve a relative URL, without having a basePath. path: './schema.json' basePath: 'undefined'.

我在网上查了这个问题，没有找到明确的答案。我看到一个解决方案，建议我应该将我的架构放在服务器上并使用 URL 地址访问它，但我不想在这一点上这样做。

此外，在某些时候，我将方案保存在一个变量中，然后将其放入 $ref它工作正常。唯一的问题是该方案在同一文件中包含了对某个元素的一些内部引用，而 Swagger 无法解析它们。

有没有办法与 $ref 一起正常工作在 swagger-ui-express ?

Answer 1

Is there a way to work properly with $ref in swagger-ui-express?

是的，有，您必须首先自己解析 YAML 文件中的引用，然后将结果提供给 Swagger UI。你可以用 json-refs 来做和 yamljs图书馆。
下面的代码片段向您展示了如何做到这一点:

const yamljs = require('yamljs');
const { resolveRefs } = require('json-refs');

/**
 * Return JSON with resolved references
 * @param {array | object} root - The structure to find JSON References within (Swagger spec)
 * @returns {Promise.<JSON>}
 */
const multiFileSwagger = (root) => {
  const options = {
    filter: ["relative", "remote"],
    loaderOptions: {
      processContent: function (res, callback) {
        callback(null, yamljs.parse(res.text));
      },
    },
  };

  return resolveRefs(root, options).then(
    function (results) {
      return results.resolved;
    },
    function (err) {
      console.log(err.stack);
    }
  );
};


const swaggerDocument = await multiFileSwagger(
  yamljs.load(path.resolve(__dirname, "./openapi/v1.yaml"))
);

您还可以使用完整示例检查该解决方案如何与 swagger-ui-express 一起使用的存储库: https://github.com/chuve/swagger-multi-file-spec