Как правильно использовать $ ref в файле swagger при работе с swagger-ui-express и swagger-jsdoc

Я начал использовать чванство с swagger-ui-express и swagger-jsdoc для автоматического документирования моего существующего API, написанного с помощью nodejs и выражающего (как описано здесь - пример).

Я столкнулся с проблемой, когда попытался добавить $ref в существующий файл схемы JSON (который находится внутри моего проекта в том же каталоге, что и все мои файлы js) в мою аннотацию.

Мой каталог выглядит так

Я попытался написать локальный путь (./schema.json) и абсолютный путь, попытался использовать #, используя множество синтаксисов, и ничего не сработало.

Моя аннотация выглядит так:

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

Я ожидал, что пользовательский интерфейс swagger покажет мне схему 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?


node.js json express swagger ref
person Liza Talis    schedule 29.12.2018    source источник
comment
на github есть открытый билет: github.com/arjun-g/ vs-swagger-viewer / issues / 45   -  person Joe    schedule 17.01.2019
comment
К сожалению, проблемы с путями внутри $ref преследуют почти каждый инструмент Swagger / OpenAPI. Проголосуйте за их исправление или опубликуйте PR на Github.   -  person Yuri    schedule 02.04.2019

Ответы (2)


arrow_upward
2
arrow_downward

Есть ли способ правильно работать с $ ref в swagger-ui-express?

Да, есть, вы должны сначала разрешить ссылки в ваших файлах YAML самостоятельно, а затем предоставить результат в пользовательский интерфейс Swagger. Вы можете сделать это с помощью 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

person chuve    schedule 19.12.2020
comment
Если вы выполняете эту функцию не по тому же пути, что и YAML-файл, подумайте о добавлении location: <your full yaml file path> к параметрам. Ссылка: github.com/whitlockjc/ json-refs / blob / master / docs / - person Marco Ottolini; 04.01.2021

arrow_upward
0
arrow_downward

у вас такая же проблема и найдите свой вопрос.

Я только что решил свою, так что думаю, что могу помочь.

Во-первых, пробовали ли вы:

schema:
      $ref: "schema.json"

без . Вот как учат в документации.

person André Tonelli    schedule 19.06.2019