Api-blueprint: Модульность

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

@rurounijones просто для пояснения, что эта функция предназначена «Чтобы иметь возможность разделить одно описание API на несколько файлов».

У кого-нибудь есть мысли по этому поводу? Согласно моему предыдущему комментарию к Drafter https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28538342

Варианты: либо добавить какое-либо средство включения/требования в верхней части чертежа, либо просто извлечь все чертежи из каталога и объединить их вместе.

Мысли?

Конкатенация проще, но я чувствую, что require будет проще в использовании, поскольку вы можете потребовать, а затем добавить что-то еще.

Будет ли это просто слепое встраивание содержимого файла, как если бы это было определено в патенте, или будут какие-то ограничения на содержимое файла (например, могут ли они иметь свой собственный заголовок yaml? Конфликты с родительским yaml?) У меня такое чувство, что без ограничений было бы лучше, но я подумал, что подниму этот вопрос.

@здне

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

Учитывая, что конкатенацию так просто накатить самостоятельно, мне кажется, что «официальный» инструмент должен быть более мощным. Я много думал об этом, пытаясь провести некоторое исследование того, как это обрабатывается другими системами.

1. Включить/требовать
   
   
   
   • Включения будут выполняться в верхней части файла, а ссылки на части файла будут внутри. Я думаю, что для этого требуется более надежная система ссылок, чем текущий синтаксис [Model Reference][] . В идеале любой узел во включенном файле должен быть адресуемым, поэтому может быть что-то вроде [github.Users.'Create A User'][] или [github][POST /users] или что-то в этом роде. (Может также понадобиться префикс, например = ). Есть ли лучший способ сослаться на конкретный узел в AST, кроме имени или URL+метода?
   
   
   • Учитывая, что у вас есть хороший способ разыменования содержимого узла, это можно сделать с помощью препроцессора C , который будет иметь множество дополнительных функций без дополнительных затрат.
   
   
2. Система шаблонов/трансклюзия
   
   
   
   • Без уценки — шаблон будет написан на отдельном языке шаблонов, поэтому файл шаблона не будет обрабатываться Snowcrash. Примером чего-то подобного является grunt-readme , который выглядит так, как будто он может работать из коробки для создания шаблона файла чертежа.
   
   
   • Уценка — это будет что-то вроде синтаксиса =[]() или :[]() , который мы обсуждали в вопросе о разработчике. Это все еще будет допустимой уценкой и разборчивым снегопадом.
   
   
3. Обе
   
   
   
   • Учитывая, что вы определяете синтаксис для ссылок на узлы ( [github]['Create A User'] ) и прямого включения ( :[/github.md](/github.md) ), кажется, что вы легко можете иметь оба. Возможно, они могли бы иметь такой же общий синтаксис, как :[]() , и синтаксический анализатор определяет, является ли это узлом или ссылкой на файл.
   
   

Есть мысли по этому поводу? Мне не хватает некоторых опций/инструментов? Я как бы склоняюсь к варианту «оба» с общим синтаксисом для включения и разыменования узлов, но, возможно, это слишком.

Учитывая, что конкатенацию так просто накатить самому, мне кажется, что "официальный" инструмент должен быть мощнее

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

Глядя на проблемы, которые необходимо решить, в основном это:

1. Ссылочные (внешние) активы — № 20 и как обсуждается в https://github.com/apiaryio/snowcrash/issues/57#issuecomment — 28564071.
2. Разделение проекта на более управляемые логические части

В целях разделения я бы рассматривал либо группу ресурсов, либо ресурс (например, не действие, пример транзакции или запрос). По крайней мере, в начале.

Объявление 1: я чувствую, что _ссылочные активы_ будут изящно рассмотрены в предложении в #20 и обсуждены https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071

Объявление 2: Я бы вообще не усложнял. Единственное, что я бы использовал для включения, — это обычный синтаксис уценки, например, [Some Text](path/to/blueprint/file.apib) или [Some Text](path/to/blueprint/file.apib#resource-name) . Для включения я бы следовал тому же принципу, что и для активов в редакторе, например, используйте : перед ссылкой. Что-то вроде https://gist.github.com/zdne/8804418#aliens-question-aliens_question

Я думаю, этого может быть достаточно для начала?

Я думаю, этого может быть достаточно для начала?

Согласованный. Я только сейчас понял, что вы проводите различие между включением «активов» и включением «ресурсов»/«групп ресурсов». Я думал обо всех них как об «узлах», которые можно включать по желанию.

Что касается второго пункта, я подумал, что было бы полезно сослаться на существующий синтаксис MultiMarkdown для включения:

This is some text.

{{some_other_file.txt}}

Another paragraph

Это кажется простым способом включения ресурсов? (или действительно, произвольный текст/узлы?)

Итак, чтобы уточнить мое мнение:

1. Я думаю, что хорошим синтаксисом для ссылочных активов будет :[]() или =[]() , как обсуждалось.
2. Я думаю, что хорошим синтаксисом для включения будет {{ }} , используемый multimarkdown.

А также для уточнения словарного запаса: я думаю, что когда вы говорите «включение», вы имеете в виду то, что я имею в виду, когда говорю «включение», то есть полную замену заполнителя текстом из другого файла.

Если я правильно понимаю, разница между "ссылкой" и "включением"/"включением" просто ради _рендеринга_, скажем, в html или pdf. Для синтаксического анализатора не имеет значения, ссылаются ли на ресурс (например) или включают его, результат будет один и тот же AST. Это правильно?

1. Я думаю, что хорошим синтаксисом для ссылочных активов будет: или = , как обсуждалось
2. Я думаю, что хорошим синтаксисом для включения будет {{ }}, который используется в множественной уценке.

Зачем иметь оба, а не только один метод? Есть ли какая-либо польза для синтаксического различия между этими двумя? Лично я предпочитаю номер один, поскольку он по-прежнему отображается как вы можете следовать в простой уценке?

Я думаю, что когда вы говорите «включение», вы имеете в виду то, что я имею в виду, когда говорю «включение», то есть полную замену заполнителя текстом из другого файла.

Согласен, теперь постараюсь использовать трансклюзию. Спасибо!

Если я правильно понимаю, разница между "ссылкой" и "включением"/"включением" просто ради рендеринга

Не совсем. На мой взгляд, ссылка (создание ссылки) должна действительно только добавить ссылку на вывод (AST), а остальное оставить на инструменте (https://github.com/apiaryio/api-blueprint/issues/20#issuecomment-26766374). )

Translcusion должен дать указание синтаксическому анализатору (или препроцессору) извлечь содержимое в...

Просто обновление здесь: это действительно запланировано и очень необходимо. Мы работаем над инструментом, который делает это возможным. Между тем, если вы не полагаетесь на онлайн-редактор Apiary, вы можете использовать что-то вроде https://gist.github.com/danvine/11087404 или другой аналогичный подход (я знаю по крайней мере несколько инструментов на основе gulp для этого).

Whiskey теперь поддерживает расширение .apib и значительно упрощает редактирование больших файлов Markdown благодаря представлению структуры: http://vimeo.com/album/3108294/video/110486733 .

http://9muses.se/erato/ и http://25.io/mou/ также поддерживают .apib, если вам нужно настольное приложение (для Mac)

Роберт КруксДиректор службы обучения
Брайтков, Инк.

29 декабря 2015 г., в 16:08, Кевин Ингерсолл уведомления[email protected] написал:

Виски теперь поддерживает .apib
расширение и упрощает редактирование больших файлов Markdown благодаря представлению схемы: http://vimeo.com/album/3108294/video/110486733

—
Ответьте на это письмо напрямую или просмотрите его на GitHub
.

Привет, @bcls и @holic , спасибо, что указали на этих редакторов!

Связанный: https://github.com/apiaryio/api-blueprint/issues/20#issuecomment -77108398

Было ли принято какое-либо решение по этому поводу основными разработчиками? Это было выдающимся с 2013 года, и до сих пор не было дано четкого ответа, можем ли мы провести черту по этому поводу, пожалуйста?

Эй , @foxx , по этому поводу еще не было четкого решения — я склоняюсь к синтаксису включения, представленному в Hercule :

FORMAT: 1A

# Gist Fox API
Gist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com).

# Group Gist

:[Gist](blueprint/gist.md)

:[Gists](blueprint/gists.md)

За исключением

`````` уценка

• Модель

+ Body

  ```
  :[](gist.json)
  ```

``````

Потому что блоки кода должны оставаться непрозрачными для парсера/препроцессора.

Также я не думаю, что включение должно работать на любом уровне — включаемые файлы сами по себе должны быть действительными чертежами.

Что касается приверженности этому — это довольно высоко в дорожной карте функций — но пока нет ETA.

Я был бы признателен за любые комментарии или мысли по этому поводу, а также о доступности функций дорожной карты.

Спасибо!

Синтаксис включения кажется лучшим предложением на данный момент, это элегантный и чистый подход, и он лучше, чем любые другие предложения, которые я видел до сих пор. Фу, +1 от меня.

есть новости по этому поводу?

подход с трансклюзией мне кажется хорошим, я не вижу в нем минусов.

Пока я предлагаю использовать Hercule и синтаксис :[Gist](blueprint/gist.md) . Будет работать над переносом его обратно в спецификацию API Blueprint и набор инструментов парсера.

Было ли что-нибудь сделано по этому вопросу? Я также хотел бы разделить большой файл apib на несколько.
Спасибо!

Привет, @adams-sarah, к сожалению, не с моей стороны. Я по-прежнему одобряю использование Hercule (https://github.com/jamesramsay/hercule), так как он работает очень хорошо — единственный недостаток в том, что вы не сможете редактировать несколько файлов на Apiary.io. Дайте мне знать, если я могу как-то помочь!

+1 к использованию геркулеса https://github.com/jamesramsay/hercule
мы используем его уже некоторое время и надеемся, что он все еще найдет свое место в спецификациях apib

:+1: за добавление этой функции.

Я также поддерживаю единую методологию TOC/index. Трансклюзия слишком гибкая, и в моем прошлом опыте она не масштабировалась в больших вики-документах.

Нам определенно придется запечь это в самом синтаксическом анализаторе для поддержки исходной карты.

Тем временем мы подготовили реальный пример, показывающий, как использовать Hercule — https://github.com/apiaryio/api.apiblueprint.org.

@zdne в нашем использовании json-схемы (через interagent/prmd) мы разделяем ее по линиям ресурсов и в основном применяем определенную структуру каталогов, чтобы подразумевать включения (более или менее она строит схему верхнего уровня, в которой есть все вещи в каталоге как подсхемы, поэтому он меняет уровни вещей). Это, очевидно, довольно специфично для того, что мы делали, и не особенно подходит для вашего случая, но мы хотели поделиться своим опытом. По сравнению с этим, я думаю, что включение кажется намного более элегантным/гибким, но определенно было бы неплохо также иметь какие-то простые средства для получения консолидированного оглавления/индекса. Возможно, это похоже на то, что мы сделали, т. е. вы создаете план uber, который будет служить в качестве этого индекса, а затем включаете/ссылаетесь на подчертежи внутри него. Я вижу, что это происходит автоматически, как хорошо, но также и как неловко, если это не делает именно то, что вы хотите. В любом случае, длинный способ сказать, что я был бы рад обсудить/поделиться своим опытом, если это будет полезно.

Каков статус этой функции?
Мы используем план Pro в Apiary.io, и нам нужна эта функция.

@DavidBM У меня была такая же проблема. как я обошел это, чтобы иметь два документа apiary.apib .

Нескомпилированный

apiary-source.apib — нескомпилированный исходный код, в котором используется функция включения .

FORMAT: 1A
HOST: https://api.example.com

# Hello World

<!-- include(blueprint/posts.apib) -->

Компиляция

Вы можете просто запустить:

aglio --input apiary-source.apib --compile --output apiary.apib

Ваш apiary.apib теперь должен включать содержимое blueprint/posts.apib внутри.

Привет спасибо! Да, но тогда вы не сможете редактировать документы в apiary.io

У нас уже было индивидуальное решение с Hercule, но смысл оплаты apiary pro для нас в том, чтобы позволить менеджерам по продукту обновлять документацию, не заходя в git. Боюсь, что это совсем блокировщик для нас и мы расторгнем договор с Пасекой, если это не решится.

Я бы не ожидал, что это будет в таком состоянии после того, как Hercule и другие инструменты были доступны так много времени.

Это очень-очень разочаровывает :(

Всем привет, извините за опоздание, повторное открытие и копание старых вещей. Если это не то место, пожалуйста, простите меня. Но, проводя исследование по разработке макетов чертежей, я нашел это обсуждение, и это самое близкое, что я мог найти до сих пор.

Я изо всех сил пытаюсь разделить свои ответы по моделям :(. Разве нельзя сослаться на модель в другую папку?
Я хотел бы иметь в папке с чертежами все мои запросы и, например, в отдельной папке моделей все мои модели сущностей (файлы MSON/MD/JSON/любые, которые подходят), чтобы легко повторно использовать их в разных ответах. У кого-нибудь есть успехи в этом?

Было бы очень здорово, если бы этот вопрос привлек внимание. У нас есть 26000 строк в нашем API Blueprint, и это невероятно усложняет управление.

Мы проводим тестирование контрактов с помощью Dredd и Aglio, но было бы здорово, если бы это было добавлено, чтобы нам не пришлось

Одна из причин заключается в том, что мы много итерируем дизайн :) Когда этот вопрос был открыт, не было MSON, и мы все еще разрываемся на включениях и ссылках.

Но для протокола, какие у вас там потребности? Это просто управление несколькими файлами и компиляция одного документа в результате, или вы также говорите о повторном использовании моделей и совместном использовании фрагментов в нескольких документах с описанием API?

Одна из причин заключается в том, что мы много итерируем дизайн :) Когда этот вопрос был открыт, не было MSON, и мы все еще разрываемся на включениях и ссылках.

Но для протокола, какие у вас там потребности? Это просто управление несколькими файлами и компиляция одного документа в результате, или вы также говорите о повторном использовании моделей и совместном использовании фрагментов в нескольких документах с описанием API?

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