Apicurio-studio: Поддержка ссылок на объекты компонентов в документах спецификации

Пример использования

Основной вариант использования, который это решит, — дать пользователям возможность централизовать свои определения типов данных, возможно, в одном файле (или наборе файлов). Затем эти типы данных можно использовать в нескольких определениях API, ссылаясь на их центральное расположение.

Соображения

Для поддержки внешних ссылок требуется ряд улучшений. Вот список в произвольном порядке:

• Библиотека модели данных (в настоящее время oai-ts-core но скоро будет apicurio-data-models ) должна быть расширена для поддержки подключаемого преобразователя ссылок. В настоящее время эти библиотеки могут разрешать только внутренние ссылки. Вместо этого потребитель библиотеки должен иметь возможность предоставить собственный преобразователь ссылок, чтобы можно было успешно разрешать внешние ссылки.

• Apicurio Studio должна поддерживать ресурс стиля «только тип данных» с редактором, ориентированным на разработку типов данных. Это позволяет использовать более конкретный рабочий процесс для создания/управления типами данных независимо от дизайна API.

• При настройке типа в редакторе API Design инструменту требуется способ выбора типов из внешних ресурсов. Нам нужно подумать, как лучше отобразить эти внешние типы для выбора пользователем. Возможно, нам нужен способ для API-проектов «импортировать» другие ресурсы/файлы, чтобы пользовательский интерфейс мог сузить выбор для пользователя и разумно отображать их. Имейте в виду, что редактору потребуется извлекать и анализировать любые внешние ресурсы, чтобы отобразить их доступные типы данных в каком-то элементе управления пользовательским интерфейсом выбора.

• Возможно, нам потребуется решить, можно ли использовать незавершенные ресурсы типа данных в качестве источника внешних ссылок при разработке API. Другими словами, должна ли быть возможность ссылаться на типы данных «моментальные снимки» в дизайне API? Или мы должны требовать, чтобы ресурс типа данных был «окончательным», прежде чем его можно будет использовать в качестве источника для внешних ссылок. Если первое, то мы не можем «доработать» дизайн API до тех пор, пока не будут завершены его зависимости. Примечание: вся эта концепция требует от нас реализации финализации ресурсов в Apicurio!

• Нам нужно решить, каким будет формат $ref при ссылке на ресурсы Apicurio. В настоящее время любой дизайн API (или теоретический ресурс типов данных) имеет уникальный идентификатор, но это непрозрачный идентификатор, который создается при создании. Этот идентификатор в настоящее время является единственным уникальным способом идентификации ресурса для целей разрешения. Как только ресурс будет завершен (если мы поддерживаем такую ​​концепцию), мы могли бы, возможно, предоставить ресурсу более удобный для человека идентификатор, а затем использовать его в URI $ref. Что бы мы ни делали, следует отметить, что при публикации ресурса в реестре API (еще одна будущая функция) любые ссылки $references в API Design должны быть разрешены реестром API каким-либо разумным образом.

Вот некоторая информация о допустимых значениях для $ref :

Несмотря на то, что значение $ref является URI, это не сетевой локатор, а только идентификатор. Это означает, что схема не обязательно должна быть доступна по этому URI, но может быть. Как будут обрабатываться URI внешней схемы, в основном зависит от реализации валидатора, но не следует предполагать, что валидатор будет извлекать сетевые ресурсы, указанные в значениях $ref.

Дополнительную информацию о ссылках можно найти в спецификации OpenAPI и в JSON Reference RFC .

Можно ли отдать приоритет реализации ссылок на типы данных из другой спецификации в Apicurio (вместо внешних ссылок изначально)?

Причина, по которой я говорю это, заключается в том, что некоторые функции перекрестных ссылок необходимы для любого нетривиального использования Swagger. Например, мы реализуем различные службы, которые совместно используют типы данных (например, адреса, люди и т. д.), и хотели бы использовать Apicurio для спецификаций для всех них. Однако на данный момент мы не можем из-за невозможности использовать перекрестные ссылки.

Можно ли отдать приоритет реализации ссылок на типы данных из другой спецификации в Apicurio (вместо внешних ссылок изначально)?

Причина, по которой я говорю это, заключается в том, что некоторые функции перекрестных ссылок необходимы для любого нетривиального использования Swagger. Например, мы реализуем различные службы, которые совместно используют типы данных (например, адреса, люди и т. д.), и хотели бы использовать Apicurio для спецификаций для всех них. Однако на данный момент мы не можем из-за невозможности использовать перекрестные ссылки.

Согласитесь, это приведет нас на территорию убийственных приложений.

@jsenko Похоже, как только мы завершим реализацию реестра, у нас появится явный приоритет от сообщества. :)

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

Я понимаю, что это заняло некоторое время, но внешние ссылки будут официально поддерживаться начиная с бета-версии 2.46, которая является следующим выпуском (надеюсь, это будет сделано завтра). Существует новый пользовательский интерфейс для импорта типов данных и ответов из других документов Apicurio Studio в текущий. Кроме того, проверка была обновлена ​​для поддержки разрешения внешних http/s, а также внутренних ссылок Apicurio. Это должно стать хорошим первым шагом к зрелой поддержке ссылок в документах.