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

Question

Я пытаюсь разбить документ API на несколько файлов JSON, которые можно редактировать независимо. Все примеры, которые я смог найти, используют схему Swagger 1.2, у которой есть объект «api»: {} для его разбивки. Кажется, что отсутствует в схеме 2.0 (http://json.schemastore.org/swagger-2.0). Все, что определяет, представляет собой единственный массив «пути», в котором он объединяет все конечные точки API в этот единственный массив. Эффект этого в swagger-ui есть одна категория «по умолчанию», в которую все входит в комплект, и я не могу сказать, чтобы разделить его.

TLDR: Как вы разделяете операции из путей в развязность 2.0 схеме

{ 
 
    "swagger": "2.0", 
 
    "info": { 
 
    "description": "My API", 
 
    "version": "1.0.0", 
 
    "title": "My API", 
 
    "termsOfService": "http://www.domain.com", 
 
    "contact": { 
 
     "name": "support@domain.com" 
 
    } 
 
    }, 
 
    "basePath": "/", 
 
    "schemes": [ 
 
    "http" 
 
    ], 
 
    "paths": { 
 
    "Authorization/LoginAPI": { 
 
     "post": { 
 
     "summary": "Authenticates you to the system and produces a session token that will be used for future calls", 
 
     "description": "", 
 
     "operationId": "LoginAPI", 
 
     "consumes": [ 
 
      "application/x-www-form-urlencoded" 
 
     ], 
 
     "produces": [ 
 
      "application/json" 
 
     ], 
 
     "parameters": [{ 
 
      "in": "formData", 
 
      "name": "UserName", 
 
      "description": "Login Username", 
 
      "required": true, 
 
      "type": "string" 
 

 
     }, { 
 
      "in": "formData", 
 
      "name": "Password", 
 
      "description": "Password", 
 
      "required": true, 
 
      "type": "string" 
 

 
     }], 
 
     "responses": { 
 
      "200": { 
 
      "description": "API Response with session ID if login is allowed", 
 
      "schema": { 
 
       "$ref": "#/definitions/Authorization" 
 
      } 
 
      } 
 
     } 
 
     } 
 
    } 
 
    } 
 
}

Answer 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 - и она все еще находится в разработке. Имейте в виду, что источником истины является спецификация(), а не схема, поэтому в случае конфликтов спецификация «выигрывает».

Edit:

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

Answer 2

Я также пытаюсь понять это, и есть полезная информация в Swagger Google group. Похоже, консенсус заключается в том, что вы можете разбить определения на отдельные файлы, если $ 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

Answer 3

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

Answer 4

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

Тогда вы можете иметь сценарий сборки в узле:

'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()); 

Подробнее о проблеме on my blog.

Answer 5

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

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

Answer 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, 


...