Разделить пути OpenApi на несколько файлов определений путей - PullRequest
Новая
       25

Разделить пути OpenApi на несколько файлов определений путей

0 голосов
/ 21 апреля 2020

Я хочу, чтобы мои пути (которых довольно много) было проще разделить на их собственные файлы.

Допустим, у меня есть два основных пути /user и /anotherPath с несколькими подпутями. Теперь у меня есть файл OpenApi spe c, пути которого ссылаются на индексный файл, который содержит ссылки на каждый путь. Определение КАЖДОГО пути с его справочными ссылками работает, но писать неудобно.

Я хочу что-то вроде этого:

openapi. json

{
...
  "paths": {
    "$ref": "paths/index.json"
  }
...
}

paths / index . json

{
  "/user": { // and everything that comes after user, e.g. /user/{userId}
    "$ref": "./user-path.json"
  },
  "/anotherPath": {  // and everything that comes after anotherPath, e.g. /anotherPath/{id}
    "$ref": "./anotherPath-path.json"
  }
}

пути / пользовательский путь. json

{
  "/user": {
    "get": {...}
  },
  "/user/{userId}": {
    "get": {...}
  }
}

пути / anotherPath-путь. json

{
  "/anotherPath": {
    "get": {...}
  },
  "/anotherPath/{id}": {
    "get": {...}
  }
}

This Кстати, всякий раз, когда я добавляю другой путь к /user или /anotherPath, я могу просто редактировать их соответствующий файл пути, например, paths / user-path. json.

EDIT1: Очевидно, это topi c обсуждается уже .. Для всех, кто заинтересован: https://github.com/OAI/OpenAPI-Specification/issues/417. Между прочим, я знаю, что $ref недопустим для объекта paths, но как только выясним, как правильно разделить, это может больше не понадобиться.

1 Ответ

0 голосов
/ 21 апреля 2020

OpenAPI не имеет понятия подпутей / вложенных путей, каждый путь является отдельной сущностью. Само ключевое слово paths не поддерживает $ref, на него можно ссылаться только на отдельные пути .

С учетом вашего пользовательского пути. json и anotherPath-path. json файлов, правильный способ ссылки на определения путей выглядит следующим образом: 

{
  ...
  "paths": {
    "/user": {
      "$ref": "paths/user-path.json#/~1user"  // ~1user is /user escaped according to JSON Pointer and JSON Reference rules
    },
    "/user/{id}": {
      "$ref": "paths/user-path.json#/~1user~1%7Bid%7D"  // ~1user~1%7Bid%7D is /user/{id} escaped 
    },
    "/anotherPath": {
      "$ref": "paths/anotherPath-path.json#/~1anotherPath"  // ~1anotherPath is /anotherPath escaped
    },
    "/anotherPath/{id}": {
      "$ref": "paths/anotherPath-path.json#/~1anotherPath~1%7Bid%7D"  // ~1anotherPath~1%7Bid%7D is /anotherPath/{id} escaped
    }
  }
  ...
}

YAML-версия: 

paths:
  /user:
    $ref: "paths/user-path.json#/~1user"
  /user/{id}:
    $ref: "paths/user-path.json#/~1user~1%7Bid%7D"
  /anotherPath:
    $ref: "paths/anotherPath-path.json#/~1anotherPath"
  /anotherPath/{id}:
    $ref: "paths/anotherPath-path.json#/~1anotherPath~1%7Bid%7D"

Если вы хотите использовать $ref в произвольных местах (кроме тех случаев, когда OAS допускает $ refs), вам придется предварительно обработать определение, используя анализатор / инструмент, который может разрешить произвольные $ refs; это даст вам действительный файл OpenAPI, который можно использовать с OpenAPI-совместимыми инструментами. Одним из таких инструментов предварительной обработки является json -refs , пример предварительной обработки можно найти здесь .

...