#tw_api_jekyll
Всем привет.
Продолжаем знакомство с Jekyll и работу над сайтом-справочником API. В прошлый раз мы вывели (уже в более удобочитаемом виде) некоторые части содержимого спецификации API на сайт.
Сегодня давайте:
- Выведем на сайт эндпоинты, их краткое (summary) и более развернутое (description) описание.
- Сделаем меню для навигации по странице.
- Начнем добавлять некоторые стили (пока по минимуму).
Вывод на сайт эндпоинтов и их описаний
Чтобы отрендерить эндпоинты, их краткое (summary) и более развернутое (description) описание, я добавил в скрипт api_reference.liquid фрагмент между тегами ....
Здесь используются уже знакомые по предыдущему посту подходы:
- Цикл for для перебора эндпоинтов. С его помощью проходимся по объекту spec.paths из спецификации openapi_spec.yaml и вложенным в него объектам, извлекая нужные данные.
- if для вывода необязательных полей, если они есть.
Обратите внимание на рендеринг названий эндпоинтов:
{{ method | upcase }} ` path `
Здесь формируется ссылка, состоящая из глагола (метода) и адреса эндпоинта. И ссылка эта ведет сама на себя.
Рендеринг меню для навигации по странице
Меню рендерится внутри тега ....
Механика схожа с используемой в предыдущем случае. Важное отличие — во фрагменте:
{{ method | upcase}} ` path `
Здесь глагол (метод) оборачивается в span, которому присваивается определенный класс. Это нужно будет в будущем для «наведения красоты».
Добавление стилей
Чтобы справочник на этом этапе выглядел уже более-менее понятно, я добавил некоторые стили.
Для этого:
- Были созданы папки: assets, а внутри нее — сss.
- В папку css был добавлен файл со стилями style.css.
- Файл style.css был подключен к шаблону страницы api_layout.html. Для этого в секцию ... был добавлен фрагмент:
Пояснения по стилям
Поясняю некоторые моменты по добавленным в style.css стилям:
Фрагмент
.wrapper {
display: flex;
}
применяет свойство display: flex для «обертки» ... внутри которой находится основной контент нашего сайта () и меню (). Это нужно для того, чтобы меню разместилось на странице слева от блока с основным контентом.
Фрагмент
.schema-toc_link {
display: block;
white-space: nowrap;
}
описывает свойства каждой ссылки в меню. Здесь нам интересно свойство white-space: nowrap. Оно блокирует перенос текста ссылки, благодаря чему ссылки в меню всегда будут в одну строку, независимо от длины.
Готово. Если вы все сделали правильно, еще больше содержимого спецификации появится на странице сайта по сравнению с предыдущим этапом.
Свериться с результатом, который должен у вас получиться, можно в ветке iteration_4 репозитория, специально подготовленного под текущую серию постов.
И не забываем, про возможность просмотра отрендеренного результата на Github Pages.
Для удобства тестирования
Также, если вы заметили, то на этом этапе также были добавлены:
- Файл petstore_spec.yaml в папку _data.
- Закомментированная строка {% assign spec = site.data.petstore_spec %} в файл api_reference.liquid.
Их можете использовать для тестирования сайта, чтобы делать это не на одной спецификации. Чтобы изменить спецификацию, которая будет рендериться, закомментируйте первую строку в файле api_reference.liquid, а вторую — раскомментируйте.
Всем привет.
Продолжаем знакомство с Jekyll и работу над сайтом-справочником API. В прошлый раз мы вывели (уже в более удобочитаемом виде) некоторые части содержимого спецификации API на сайт.
Сегодня давайте:
- Выведем на сайт эндпоинты, их краткое (summary) и более развернутое (description) описание.
- Сделаем меню для навигации по странице.
- Начнем добавлять некоторые стили (пока по минимуму).
Вывод на сайт эндпоинтов и их описаний
Чтобы отрендерить эндпоинты, их краткое (summary) и более развернутое (description) описание, я добавил в скрипт api_reference.liquid фрагмент между тегами ....
Здесь используются уже знакомые по предыдущему посту подходы:
- Цикл for для перебора эндпоинтов. С его помощью проходимся по объекту spec.paths из спецификации openapi_spec.yaml и вложенным в него объектам, извлекая нужные данные.
- if для вывода необязательных полей, если они есть.
Обратите внимание на рендеринг названий эндпоинтов:
{{ method | upcase }} ` path `
Здесь формируется ссылка, состоящая из глагола (метода) и адреса эндпоинта. И ссылка эта ведет сама на себя.
Рендеринг меню для навигации по странице
Меню рендерится внутри тега ....
Механика схожа с используемой в предыдущем случае. Важное отличие — во фрагменте:
{{ method | upcase}} ` path `
Здесь глагол (метод) оборачивается в span, которому присваивается определенный класс. Это нужно будет в будущем для «наведения красоты».
Добавление стилей
Чтобы справочник на этом этапе выглядел уже более-менее понятно, я добавил некоторые стили.
Для этого:
- Были созданы папки: assets, а внутри нее — сss.
- В папку css был добавлен файл со стилями style.css.
- Файл style.css был подключен к шаблону страницы api_layout.html. Для этого в секцию ... был добавлен фрагмент:
Пояснения по стилям
Поясняю некоторые моменты по добавленным в style.css стилям:
Фрагмент
.wrapper {
display: flex;
}
применяет свойство display: flex для «обертки» ... внутри которой находится основной контент нашего сайта () и меню (). Это нужно для того, чтобы меню разместилось на странице слева от блока с основным контентом.
Фрагмент
.schema-toc_link {
display: block;
white-space: nowrap;
}
описывает свойства каждой ссылки в меню. Здесь нам интересно свойство white-space: nowrap. Оно блокирует перенос текста ссылки, благодаря чему ссылки в меню всегда будут в одну строку, независимо от длины.
Готово. Если вы все сделали правильно, еще больше содержимого спецификации появится на странице сайта по сравнению с предыдущим этапом.
Свериться с результатом, который должен у вас получиться, можно в ветке iteration_4 репозитория, специально подготовленного под текущую серию постов.
И не забываем, про возможность просмотра отрендеренного результата на Github Pages.
Для удобства тестирования
Также, если вы заметили, то на этом этапе также были добавлены:
- Файл petstore_spec.yaml в папку _data.
- Закомментированная строка {% assign spec = site.data.petstore_spec %} в файл api_reference.liquid.
Их можете использовать для тестирования сайта, чтобы делать это не на одной спецификации. Чтобы изменить спецификацию, которая будет рендериться, закомментируйте первую строку в файле api_reference.liquid, а вторую — раскомментируйте.