AsyncAPI HTML шаблон: Включение ссылочных схем и сообщений

Чтобы включить ссылочные схемы и сообщения в генерацию HTML-шаблонов с помощью AsyncAPI CLI, вы можете использовать параметр --map-base-url для сопоставления внешних ссылок на схемы с локальными папками и убедиться, что ваши шаблоны настроены на обработку ссылочных компонентов. Генератор AsyncAPI предоставляет несколько параметров конфигурации и переменных шаблона, которые позволяют получать доступ и включать ссылочные схемы и сообщения в ваш HTML-вывод.

Содержание

• Понимание проблемы со ссылочными компонентами
• Использование параметра --map-base-url
• Конфигурация шаблонов для ссылочных компонентов
• Подходы к разработке продвинутых шаблонов
• Лучшие практики управления ссылочными документами
• Устранение распространенных проблем

Понимание проблемы со ссылочными компонентами

Когда вы разделяете вашу спецификацию AsyncAPI на несколько документов для лучшей переиспользуемости, вы создаете ситуацию, при которой схемы и сообщения определяются в одном документе, но ссылаются на них из других. Структура документа AsyncAPI включает раздел components, где могут быть определены переиспользуемые элементы, такие как схемы и сообщения, которые затем могут быть сосланы с помощью синтаксиса $ref.

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

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

Использование параметра --map-base-url

Основным решением для включения ссылочных схем и сообщений является использование параметра --map-base-url в команде AsyncAPI CLI. Этот параметр сопоставляет внешние ссылки на схемы из базового URL с локальными папками, позволяя генератору разрешать и включать ссылочные компоненты.

Вот как его использовать:

asyncapi generate fromTemplate ./main-api-spec.json @asyncapi/html-template@3.0.0 \
  --use-new-generator \
  -o ./build/ \
  --force-write \
  --map-base-url https://schema.example.com/crm/:./test/docs/

В этом примере:

• https://schema.example.com/crm/ - это базовый URL, на котором размещены внешние схемы
• ./test/docs/ - это локальная папка, содержащая документы ссылочных схем

Параметр --map-base-url работает путем замены базового URL в путях $ref на указанный локальный путь к папке, позволяя генератору находить и обрабатывать файлы ссылочных схем локально.

Вы также можете использовать несколько параметров --map-base-url, если у вас есть схемы, размещенные в разных базовых URL:

asyncapi generate fromTemplate ./main-api-spec.json @asyncapi/html-template@3.0.0 \
  --map-base-url https://schemas.company.com/auth/:./shared/schemas/auth/ \
  --map-base-url https://schemas.company.com/crm/:./shared/schemas/crm/

Конфигурация шаблонов для ссылочных компонентов

Помимо параметров CLI, вам может потребоваться настроить ваш HTML-шаблон для правильной обработки и отображения ссылочных компонентов. HTML-шаблон AsyncAPI предоставляет несколько переменных шаблона и параметров контекста, которые могут помочь вам получить доступ к ссылочным схемам и сообщениям.

Доступные переменные шаблона

Генератор предоставляет несколько переменных шаблона, которые дают доступ к различным частям документа AsyncAPI:

• $$message$$ - Предоставляет доступ к текущему отображаемому сообщению с переменными message и messageName
• $$schema$$ - Предоставляет доступ к текущей схеме с переменными schema и schemaName
• $$channel$$ - Предоставляет доступ к текущему каналу с переменными channel и channelName

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

Конфигурация контекста шаблона

Функция контекста шаблона позволяет получить содержимое документа AsyncAPI и внедрить динамические значения в ваши шаблоны. При генерации HTML контекст включает все разрешенные ссылки, делая их доступными для обработки шаблона.

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

// В конфигурации вашего шаблона
module.exports = {
  context: {
    includeReferenced: true, // Это гарантирует включение ссылочных компонентов
    // Другие параметры контекста
  }
};

Подходы к разработке продвинутых шаблонов

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

Пользовательские списки схем и сообщений

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

<!-- Пользовательский шаблон списка схем -->
<div class="schemas-section">
  <h2>Все схемы</h2>
  <ul>
    {% for schemaName, schema in asyncapi.components.schemas %}
      <li>
        <strong>{{ schemaName }}</strong>
        <div class="schema-details">
          {{ schema | json }}
        </div>
      </li>
    {% endfor %}
  </ul>
</div>

Этот шаблон перебирает все схемы в разделе components.schemas, который включает как явно определенные, так и ссылочные схемы после применения сопоставления --map-base-url.

Интеграция компонентов React

HTML-шаблон AsyncAPI использует компоненты React под капотом. Вы можете использовать эти компоненты для создания более сложных отображений ссылочных компонентов:

import { Schema, Message } from '@asyncapi/react-component';

function CustomSchemaList({ asyncapi }) {
  return (
    <div>
      <h2>Все доступные схемы</h2>
      {Object.entries(asyncapi.components().schemas()).map(([name, schema]) => (
        <Schema key={name} schema={schema} name={name} />
      ))}
    </div>
  );
}

Лучшие практики управления ссылочными документами

При работе со ссылочными документами AsyncAPI следуйте этим лучшим практикам для обеспечения полной генерации документации:

1. Организуйте репозиторий схем

Создайте хорошо организованную структуру репозитория схем, которая упростит управление и ссылку на компоненты:

/schemas
  /auth
    user-schema.yaml
    permission-schema.yaml
  /crm
    customer-schema.yaml
    order-schema.yaml
  /shared
    common-types.yaml

2. Используйте последовательное ссылание

Обеспечьте последовательные шаблоны ссылок по вашим документам AsyncAPI:

# В вашей основной спецификации API
components:
  schemas:
    User:
      $ref: './shared/schemas/auth/user-schema.yaml#/User'
    Customer:
      $ref: './shared/schemas/crm/customer-schema.yaml#/Customer'

3. Проверяйте ссылочные документы

Используйте AsyncAPI Studio для проверки ваших спецификаций и убедитесь, что все ссылки правильно разрешены перед генерацией документации.

4. Используйте систему контроля версий

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

Устранение распространенных проблем

При работе со ссылочными компонентами вы можете столкнуться с несколькими распространенными проблемами:

Ссылки не разрешаются

Если ссылки не разрешаются правильно, проверьте:

1. Сопоставление базового URL: Убедитесь, что параметр --map-base-url правильно сопоставляет ваши базовые URL с локальными папками
2. Пути к файлам: Проверьте, что пути в ваших операторах $ref соответствуют фактическим расположениям файлов
3. Расширения файлов: Убедитесь, что ссылочные файлы имеют правильные расширения и доступны

Отсутствующие компоненты в сгенерированном выводе

Если компоненты все еще отсутствуют в вашем HTML-выводе:

1. Конфигурация шаблона: Убедитесь, что ваш шаблон настроен на доступ к полному контексту документа
2. Версия генератора: Используйте флаг --use-new-generator для лучшего разрешения ссылок
3. Режим отладки: Включите режим отладки с помощью --debug для просмотра подробных сообщений об ошибках

Проблемы с производительностью при больших наборах документов

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

1. Инкрементальная генерация: Используйте флаг -w, --watch для разработки, чтобы избежать полной регенерации
2. Выборочная генерация: Используйте -n, --no-overwrite для пропуска неизмененных файлов
3. Оптимизация шаблонов: Оптимизируйте ваши шаблоны для обработки только необходимых компонентов

Заключение

Чтобы эффективно включать ссылочные схемы и сообщения в генерацию HTML-шаблонов с помощью AsyncAPI CLI, вам необходимо объединить правильную конфигурацию CLI с соответствующей разработкой шаблонов. Ключевым решением является использование параметра --map-base-url для сопоставления внешних ссылок на схемы с локальными папками, что позволяет генератору находить и обрабатывать ссылочные компоненты.

Для достижения наилучших результатов:

• Всегда используйте --map-base-url с правильным сопоставлением URL-адресов с папками
• Настраивайте ваши шаблоны для доступа к полному контексту документа
• Следуйте лучшим практикам для организации и ссылок на ваши документы схем
• Тщательно тестируйте вашу настройку перед генерацией окончательной документации

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

Источники

1. AsyncAPI CLI HTML template includes messages from referenced documents - Stack Overflow
2. Usage | AsyncAPI Initiative for event-driven APIs
3. Generator usage | AsyncAPI Initiative for event-driven APIs
4. AsyncAPI document structure | AsyncAPI Initiative for event-driven APIs
5. Template development | AsyncAPI Initiative for event-driven APIs
6. Template context | AsyncAPI Initiative for event-driven APIs
7. GitHub - asyncapi/html-template
8. Async API documentation 101 - DEV Community