Как разбить swagger 2.0 JSON файл на несколько модулей

Ответ 1

На самом деле вы задаете несколько вопросов в одном, и я попробую ответить на них.

В Swagger 1.2 и до него разделение файлов было обязательным и искусственным. Это подразумевалось как способ групповых операций, а Swagger 2.0 предлагает и альтернативный метод для этого (подробнее об этом в ближайшее время).

Swagger 2.0 - это действительно один файл, который позволяет использовать внешние файлы везде, где используется $ref. Вы не можете разделить одну службу на несколько файлов и объединить их как одну, но вы можете указать операции для определенных путей извне (опять же, используя свойство $ref).

В настоящее время мы завершаем процесс сопоставления нескольких микросервисов в одну коллекцию, но в конечном итоге каждый микросервис по-прежнему будет одним файлом.

Как уже упоминалось, группировка операций в Swagger 2.0 изменилась, и концепция "ресурса" больше не существует. Вместо этого есть метки (с свойством "tags"), которые могут быть назначены за операцию. tags - это массив значений, и в отличие от предыдущих версий каждая операция может существовать под несколькими тегами, если это необходимо. В Swagger-UI все операции, которые не имеют определенных тегов, попадут под тегом default, который является поведением, которое вы видели. На объекте верхнего уровня есть дополнительное свойство tags, которое позволяет добавлять описания к тегам и устанавливать их порядок, но необязательно включать его.

Как последнее замечание, я понятия не имею, как json-схема Swagger 2.0 оказалась в http://json.schemastore.org/swagger-2.0, но это, безусловно, не обновляется. Самая современная схема может быть найдена здесь - http://swagger.io/v2/schema.json - и она все еще находится в разработке. Имейте в виду, что источником истины является спецификация (https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md), а не схема, поэтому в случае конфликтов спецификация" выигрывает.

Edit:

Мы только что опубликовали руководство по ссылке. Это может помочь в некоторых случаях использования - https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/v2.0/REUSE.md

Ответ 2

Я написал об этом в этом сообщении в блоге. В основном вы можете использовать библиотеку JSON Refs, чтобы разрешить все ваши маленькие файлы Swagger в один большой и использовать их в инструментах.

Ответ 3

Если JSON ref не работает для вас, может быть полезно написать собственный конкатенатор. Ну, вместо того, чтобы писать свои собственные, вы можете фактически использовать то, что уже есть. Любой шаблонный движок будет делать. В моем случае Handlebars оказались очень полезными (потому что Handlebars на самом деле сохраняет отступы, которые идеально подходят для файлов Yaml, поскольку они чувствительны к регистру).

Затем вы можете создать сборку script в Node:

'use strict';

var hbs = require('handlebars');
var fs  = require('fs');

var dir = __dirname + '/your_api_dir';

var files = fs.readdirSync(dir);

files.forEach((fileName) => {
  var raw = fs.readFileSync(dir + '/' + fileName, 'utf8');
  hbs.registerPartial(file, raw);
});

var index = fs.readFileSync(dir + '/index.yaml');

var out = hbs.compile(index.toString());

Подробнее о проблеме в моем блоге.

Ответ 4

Обратите внимание, что RepreZen API Studio теперь поддерживает проекты с несколькими файлами Swagger/Open API с помощью синтаксиса $ref, обсуждаемого здесь. Таким образом, вы можете разбить большие проекты Swagger на модули, чтобы обеспечить повторное использование и совместное сотрудничество. Затем вы можете использовать встроенный нормализатор Swagger для создания единого консолидированного файла Swagger, когда вам нужно взять модель вашего API за пределы среды разработки/разработки.

Примечание: в интересах полного раскрытия информации я являюсь менеджером по продукции в RepreZen. Я наткнулся на эту тему на прошлой неделе и подумал, что я заберусь.

Ответ 5

Я тоже пытаюсь понять это, и там есть полезная информация в группе Swagger Google. Похоже, консенсус заключается в том, что вы можете разбить определения на отдельные файлы, если $ref указывает на абсолютный URL-адрес. Пример здесь:

https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions.json#L32

https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions_part1.json

Ответ 6

Если json не работает для вас, вы также можете использовать node.js, вы также можете использовать module.exports

У меня есть свои определения в модулях, и я могу требовать модуль внутри модуля:

const params = require(./parameters);
module.exports = {
  description: 'Articles',
  find: {
    description: 'Some description of the method', 
    summary: 'Some summary',
    parameters: [
        params.id,
        params.limit,


...