Знания лишними не бывают. Особенно, когда они про популярный SSG
А давайте замутим небольшую серию постов про Jekyll и Liquid.
Погрузимся в это все (совсем неглубоко), конечно же, на практике: сделаем своими руками страничку с простым генератором справочника API из OpenAPI-спецификации. А дальше вы сможете его доработать под свои нужды, если захотите.
Вы в в деле?
Если в деле, ставьте под постом 🔥 (и друзей своих зовите, кому это может быть интересно).
Если нет — ставьте 👀.
А давайте замутим небольшую серию постов про Jekyll и Liquid.
Погрузимся в это все (совсем неглубоко), конечно же, на практике: сделаем своими руками страничку с простым генератором справочника API из OpenAPI-спецификации. А дальше вы сможете его доработать под свои нужды, если захотите.
Вы в в деле?
Если в деле, ставьте под постом 🔥 (и друзей своих зовите, кому это может быть интересно).
Если нет — ставьте 👀.
🔥43👀4👏3
#tw_api_jekyll
Привет, как договорились выше, начинаем знакомство с Jekyll и Liquid на практике. Это и серия других постов по теме будут помечены тегом #tw_api_jekyll. В рамках серии постов мы попробуем наладить сборку сайта-справочника API из спецификации в формате OpenAPI.
Сегодня мы подготовим «почву» для нашего справочника.
Для этого выполните следующее:
1. Установите себе на компьютер(приобнял пользователей Windows — у вас самая длинная инструкция ) .
2. Создайте на своем компьютере новый проект с помощью команды (в терминале, консоли).
Здесь вместо
3. После этого перейдите в созданную папку:
4. Запустите сайт командой:
Если все сделано правильно, сайт с настройками по умолчанию будет доступен по адресу
Откройте папку
Давайте внесем в эту структуру некоторые изменения, чтобы адаптировать сайт под наши нужды.
Сделайте следующее:
1. Удалите папку
2. Переименуйте файл
3. Откройте файл
4. В начало файла
Если все сделали правильно, по адресу
На сегодня все. «Почва» для дальнейшей работы готова. В следующий раз мы добавим свой шаблон для сайта-справочника API и спецификацию, из которой он будет собираться.
Привет, как договорились выше, начинаем знакомство с Jekyll и Liquid на практике. Это и серия других постов по теме будут помечены тегом #tw_api_jekyll. В рамках серии постов мы попробуем наладить сборку сайта-справочника API из спецификации в формате OpenAPI.
Сегодня мы подготовим «почву» для нашего справочника.
Для этого выполните следующее:
1. Установите себе на компьютер
Jekyll и все зависимости по инструкции для вашей ОС со страницы Installation документации этого SSG 2. Создайте на своем компьютере новый проект с помощью команды (в терминале, консоли).
jekyll new tw_api_jekyll
Здесь вместо
tw_api_jekyll можно использовать любое другое имя. Это — имя папки, в которой будет создан новый проект (сайт). Чтобы у нас с вами не было «рассинхрона», предлагаю оставить его как есть.3. После этого перейдите в созданную папку:
cd tw_api_jekyll
4. Запустите сайт командой:
bundle exec jekyll serve
Если все сделано правильно, сайт с настройками по умолчанию будет доступен по адресу
http://localhost:4000.Откройте папку
tw_api_jekyll в файловом менеджере, в IDE или посмотрите ее структуру в консоли (как вам удобно). Вы увидите следующую картину:
tw_api_jekyll /
├── _posts/ # Папка для постов
├── _site/ # Папка со сгенерированными страницами сайта
├── Gemfile # Файл зависимостей Ruby
├── Gemfile.lock # Конкретные версии зависимостей (генерируется автоматически)
├── _config.yml # Основной конфигурационный файл
├── .jekyll-cache/ # Кеш для ускорения сборки
├── 404.html # Шаблон для станицы 404
├── about.markdown # Страница about
└── index.markdown # Главная страница
Давайте внесем в эту структуру некоторые изменения, чтобы адаптировать сайт под наши нужды.
Сделайте следующее:
1. Удалите папку
_posts/ и файл about.markdown. Это мы делаем потому, что наш сайт-справочник API будет одностраничным.2. Переименуйте файл
index.markdown в index.md. Делать это не обязательно, с обоими расширениями Jekyll работает без проблем. Давайте считать это вкусовщиной: просто я привык использовать для Markdown-файлов расширение .md.3. Откройте файл
index.md и во фронтметтре (это фрагмент вверху страницы, заключенный в ---) удалите привязку к стандартному шаблону. Для этого удалите layout: home (или закомментируйте, это нам в будущем понадобится).4. В начало файла
index.md добавьте заголовок # Справочник TW_api. Сохраните файл.Если все сделали правильно, по адресу
http://localhost:4000 будет находиться страница с заголовком # Справочник TW_api без какой-либо разметки (т.к. мы «отвязались» от стандартного шаблона).На сегодня все. «Почва» для дальнейшей работы готова. В следующий раз мы добавим свой шаблон для сайта-справочника API и спецификацию, из которой он будет собираться.
🔥9👍4👨💻2
#tw_api_jekyll
Привет. Продолжаем знакомство с Jekyll. В прошлый раз мы «подготовили почву» для нашего сайта-справочника.
Сегодня:
- добавим шаблон для сайта,
- добавим источник (спецификацию в формате Open API), из которого будет собираться справочник,
- хоть в каком-нибудь виде выведем содержимое спецификации на сайт.
1. Добавление шаблона
Чтобы добавить шаблон для нашего сайта, сделайте следующее:
1.1. Создайте в корне директории с сайтом папку _layouts. Именно в ней по умолчанию Jekyll ищет шаблоны для страниц сайта.
1.2. Создайте в этой папке файл api_layout.html со следующим содержимым:
1.3. В файле
2. Добавление спецификации, из которой будет собираться справочник
Чтобы добавить спецификацию, сделайте следующее:
2.1. Создайте в корне репозитория с сайтом папку
2.2. В папке
2.3. В файл
3. Вывод содержимого спецификации на сайт
Чтобы вывести спецификацию на сайт, сделайте следюущее:
3.1. Создайте в корне репозитория с сайтом папку
3.2. В папке
3.3. В файл
3.4. В файл
При рендеринге страницы Jekyll дойдет до этого кода, увидит там include, пойдет в папку
Готово, если вы все сделали правильно, содержимое спецификации появится на странице сайта (не забываем, что рендеринг запускается командой
Да, выглядит это пока некрасиво (но главное — что содержимое спецификации выводится на страницу). Но все еще впереди. Красоту будем наводить в следующих постах.
Свериться с результатом, который должен у вас появиться, можно в ветке iteration_2 репозитория, специально подготовленного под текущую серию постов.
Привет. Продолжаем знакомство с Jekyll. В прошлый раз мы «подготовили почву» для нашего сайта-справочника.
Сегодня:
- добавим шаблон для сайта,
- добавим источник (спецификацию в формате Open API), из которого будет собираться справочник,
- хоть в каком-нибудь виде выведем содержимое спецификации на сайт.
1. Добавление шаблона
Чтобы добавить шаблон для нашего сайта, сделайте следующее:
1.1. Создайте в корне директории с сайтом папку _layouts. Именно в ней по умолчанию Jekyll ищет шаблоны для страниц сайта.
1.2. Создайте в этой папке файл api_layout.html со следующим содержимым:
<!doctype html>
<html lang="ru">
<head>
<meta charset="utf-8">
<noscript>{{ page.noscript }}</noscript>
</head>
<body>
{{ content }}
<footer>
</footer>
</body>
</html>
1.3. В файле
index.md (его мы создали в прошлый раз и «отвязали» от шаблона по умолчанию), в frontmatter укажите, что для этой страницы будет использоваться шаблон api_layout.html:
---
layout: api_layout
---
2. Добавление спецификации, из которой будет собираться справочник
Чтобы добавить спецификацию, сделайте следующее:
2.1. Создайте в корне репозитория с сайтом папку
_data. Это папка, которая предназначенная для хранения структурированных данных в форматах YAML, JSON или CSV. Очень удобно, чтобы разделить контент, который нам нужно рендерить, от шаблонов, скриптов и пр.2.2. В папке
_data создайте файл openapi_spec.yaml.2.3. В файл
openapi_spec.yaml поместите спецификацию (эту спецификацию мы с вами разработали на Курсе по проектированию и документированию API). Скопировать ее можно здесь.3. Вывод содержимого спецификации на сайт
Чтобы вывести спецификацию на сайт, сделайте следюущее:
3.1. Создайте в корне репозитория с сайтом папку
_includes. В Jekyll эта папка используется для хранения переиспользуемых фрагментов кода.3.2. В папке
_includes создайте файл api_reference.liquid. Его как раз мы и будем потом переиспользовать. Здесь будет находиться скрипт для вывода содержимого спецификации на страницу с необходимыми преобразованиями. Подробнее про Liquid — в документации.3.3. В файл
api_reference.liquid добавьте код для вывода содержимого спецификации openapi_spec.yaml на страницу сайта:
{% assign spec = site.data.openapi_spec %}
<div class="schema_wrapper">
{{ spec }}
</div>
3.4. В файл
index.md добавьте код, который как раз и будет переиспользовать наш шаблон api_reference.liquid:
{% include api_reference.liquid %}
При рендеринге страницы Jekyll дойдет до этого кода, увидит там include, пойдет в папку
_include и выполнит liquid-скрипт в файле api_reference.liquid.Готово, если вы все сделали правильно, содержимое спецификации появится на странице сайта (не забываем, что рендеринг запускается командой
bundle exec jekyll serve).Да, выглядит это пока некрасиво (но главное — что содержимое спецификации выводится на страницу). Но все еще впереди. Красоту будем наводить в следующих постах.
Свериться с результатом, который должен у вас появиться, можно в ветке iteration_2 репозитория, специально подготовленного под текущую серию постов.
1👨💻7🔥4👏3
#продолжи_мысль_SE
Зачем админ просит публичный ключ. Или что происходит при подключении к серверу по SSH
Если вы работаете аналитиком, архитектором, техническим писателем и «около этого», наверняка сталкивались с просьбами от админов вроде «Скинь свой публичный ключ». После того как вы это сделаете, получаете возможность «ходить» по серверам на стейдже, препроде, проде и т.д.
А зачем вообще нужен этот ключ и что происходит, когда мы пытаемся подключиться к серверу по SSH? Давайте разберемся (без захода в дебри).
Публичный и приватный ключ
Публичный ключ SSH (пример:
И здесь важно запомнить: никому не передавайте свой приватный ключ. А публичный можете отправлять по запросу без проблем.
Зачем админу ваш публичный ключ
После получения публичного ключа админ помещает его в файл
А подключение происходит так (при условии, что оно не первое, про особенности первого — ниже):
1. Вы вводите в консоли команду для подключения к серверу (например,
2. Сервер находит ваш публичный ключ в
3. Сервер генерирует число, шифрует его с использованием вашего публичного ключа (генерирует challenge) и отправляет challenge в ответ вашему компьютеру.
4. Установленный на вашем компьютере SSH-агент расшифровывает с его помощью приватного ключа полученный challenge. Затем он создает подпись (которая содержит хеш от расшифрованного числа и данные сессии) и отправляет ее серверу.
5. Получив подпись, сервер сверяет ее с подписью, вычисленной локально с помощью публичного ключа (она тоже содержит хеш от числа и данные сессии).
6. Если подписи совпали, сервер разрешает доступ.
Этот процесс описан на диаграмме, прикрепленной к посту.
Если вы подключаетесь к серверу впервые
В этом случае после ввода в консоли команды для подключения к серверу и отправки запроса, сервер предъявляет в ответ свой публичный ключ (fingerprint). Получив его, компьютер спрашивает, добавить ли в доверенные. При положительном ответе fingerprint сервера добавляется в
Почему публичный ключ, а не логин и пароль
Вариант с публичным ключом считается более безопасным.
При использовании логина и пароля последний передается по сети. А значит, есть вероятность его компрометации в случае перехвата злоумышленниками. Конечно, полностью отказываться от этого способа не стоит. Если вы, к примеру, работаете в приватной сети, изолированной от внешнего мира, логин и пароль — вполне ОК. Если же вы подключаетесь к серверу через публичную сеть, использование публичного и приватного ключей — must have.
Можно ли расшифровать число, отправляемое сервером с помощью публичного ключа
Если злоумышленник попытается использовать публичный ключ для расшифровки числа от сервера, чтобы выдать себя за вас, ничего не получится. Ведь здесь используются алгоритмы асимметричного шифрования, которые подразумевают соответствие принципам:
• Невозможность использования публичного ключа для расшифровки данных, даже если они зашифрованы им же.
• Невозможность создания подписи с помощью публичного ключа.
• Невозможность (ну или почти невозможность) математически вычислить приватный ключ с помощью публичного. Это требует колоссальных ресурсов (тысячи лет).
Участвую в конкурсе «Продолжи мысль» от @systems_education
Зачем админ просит публичный ключ. Или что происходит при подключении к серверу по SSH
Если вы работаете аналитиком, архитектором, техническим писателем и «около этого», наверняка сталкивались с просьбами от админов вроде «Скинь свой публичный ключ». После того как вы это сделаете, получаете возможность «ходить» по серверам на стейдже, препроде, проде и т.д.
А зачем вообще нужен этот ключ и что происходит, когда мы пытаемся подключиться к серверу по SSH? Давайте разберемся (без захода в дебри).
Публичный и приватный ключ
Публичный ключ SSH (пример:
user_rsa.pub) всегда существует в паре с приватным ключом, который носит такое же название, но не имеет расширения .pub (для нашего примера — user_rsa). Без приватного ключа публичный будет бесполезным.И здесь важно запомнить: никому не передавайте свой приватный ключ. А публичный можете отправлять по запросу без проблем.
Зачем админу ваш публичный ключ
После получения публичного ключа админ помещает его в файл
~/.ssh/authorized_keys на сервере. И после этого вы можете подключаться к серверу по SSH.А подключение происходит так (при условии, что оно не первое, про особенности первого — ниже):
1. Вы вводите в консоли команду для подключения к серверу (например,
ssh user@93.184.216.34).2. Сервер находит ваш публичный ключ в
~/.ssh/authorized_keys.3. Сервер генерирует число, шифрует его с использованием вашего публичного ключа (генерирует challenge) и отправляет challenge в ответ вашему компьютеру.
4. Установленный на вашем компьютере SSH-агент расшифровывает с его помощью приватного ключа полученный challenge. Затем он создает подпись (которая содержит хеш от расшифрованного числа и данные сессии) и отправляет ее серверу.
5. Получив подпись, сервер сверяет ее с подписью, вычисленной локально с помощью публичного ключа (она тоже содержит хеш от числа и данные сессии).
6. Если подписи совпали, сервер разрешает доступ.
Этот процесс описан на диаграмме, прикрепленной к посту.
Если вы подключаетесь к серверу впервые
В этом случае после ввода в консоли команды для подключения к серверу и отправки запроса, сервер предъявляет в ответ свой публичный ключ (fingerprint). Получив его, компьютер спрашивает, добавить ли в доверенные. При положительном ответе fingerprint сервера добавляется в
known_hosts на вашем компьютере. И теперь все работает, как описано выше (при запросе подключения к серверу он предъявляет свой fingerprint, чтобы подтвердить, что это реально он).Почему публичный ключ, а не логин и пароль
Вариант с публичным ключом считается более безопасным.
При использовании логина и пароля последний передается по сети. А значит, есть вероятность его компрометации в случае перехвата злоумышленниками. Конечно, полностью отказываться от этого способа не стоит. Если вы, к примеру, работаете в приватной сети, изолированной от внешнего мира, логин и пароль — вполне ОК. Если же вы подключаетесь к серверу через публичную сеть, использование публичного и приватного ключей — must have.
Можно ли расшифровать число, отправляемое сервером с помощью публичного ключа
Если злоумышленник попытается использовать публичный ключ для расшифровки числа от сервера, чтобы выдать себя за вас, ничего не получится. Ведь здесь используются алгоритмы асимметричного шифрования, которые подразумевают соответствие принципам:
• Невозможность использования публичного ключа для расшифровки данных, даже если они зашифрованы им же.
• Невозможность создания подписи с помощью публичного ключа.
• Невозможность (ну или почти невозможность) математически вычислить приватный ключ с помощью публичного. Это требует колоссальных ресурсов (тысячи лет).
Участвую в конкурсе «Продолжи мысль» от @systems_education
2🔥12👍10🤝7❤1
#tw_api_jekyll
Всем привет.
Продолжаем знакомство с Jekyll. В прошлый раз мы вывели (пока не совсем в удобочитаемом виде) содержимое спецификации API на сайт.
Давайте начнем приводить все в более-менее приятный вид. Сегодня мы:
- Посмотрим на документацию OpenAPI Specification.
- Выведем на сайт некоторые поля «первого» уровня схемы API.
Спецификация API (у нас она размещена в файле
Если пробежаться по
Вывод полей «первого» уровня на сайт
Если посмотреть документацию OpenAPI Specification V 3.0.0, вы увидите, что спецификация API содержит фиксированный набор полей. Часть из них обязательные (
При подготовке сегодняшнего поста, для наглядности, я добавил в нашу спецификацию
Итак, давайте выведем на страницу поля «первого уровня»:
-
Остальными займемся в следующих постах.
Для этого измените файл
Содержимое тега
Что здесь происходит (поясняю некоторые фрагменты, т.к. для большинства одинаковая механика)?
-
- В условии
- Если поле servers существует в спецификации, рендерится его содержимое. Для этого используется цикл
Что еще нужно сделать на этом этапе
Со страницы
Готово. Если вы все сделали правильно, часть содержимого спецификации появится на странице сайта (не забываем, про
Пока без CSS: этим займемся на следующих этапах.
Свериться с результатом, который должен получиться, можно в ветке iteration_3.
Всем привет.
Продолжаем знакомство с Jekyll. В прошлый раз мы вывели (пока не совсем в удобочитаемом виде) содержимое спецификации API на сайт.
Давайте начнем приводить все в более-менее приятный вид. Сегодня мы:
- Посмотрим на документацию OpenAPI Specification.
- Выведем на сайт некоторые поля «первого» уровня схемы API.
Спецификация API (у нас она размещена в файле
_data/openapi_spec.yaml) пишется в соответствии с определенным набором правил. И для OpenAPI это набор правил — OpenAPI Specification соответствующей версии (в нашем случае это OpenAPI Specification V 3.0.0). В ней рассмотрено, что должна (и может) содержать спецификация API, и как это все описать. То есть если мы взялись писать генератор справочника API из OpenAPI-спецификации в формате OpenAPI Specification V 3.0.0, без ее изучения не обойтись (это вам задание на дом).Если пробежаться по
OpenAPI Specification V 3.0.0, становится видно, что спецификация API (напоминаю, что у нас это _data/openapi_spec.yaml) — это один большой объект, который включает поля разных типов. И чтобы отрендерить нужную нам информацию (поля объекта), нужно обратиться к этим полям в скрипте _includes/api_reference.liquid, которым мы в предыдущем посте выводили схему на страницу, и обработать их удобным нам способом.Вывод полей «первого» уровня на сайт
Если посмотреть документацию OpenAPI Specification V 3.0.0, вы увидите, что спецификация API содержит фиксированный набор полей. Часть из них обязательные (
openapi, info и paths), другие — нет.При подготовке сегодняшнего поста, для наглядности, я добавил в нашу спецификацию
_data/openapi_spec.yaml поле servers (необязательное), чтобы потренироваться в выводе обязательных и необязательных полей страницу нашего сайта-справочника. И вы его себе тоже можете добавить.Итак, давайте выведем на страницу поля «первого уровня»:
-
openapi,
- info,
- servers.Остальными займемся в следующих постах.
Для этого измените файл
_includes/api_reference.liquid.Содержимое тега
<div class="schema_wrapper"> </div> замените на:
<!-- Рендеринг обязательных параметров схемы: заголовок,версия и описание API -->
<h1 class="api-noscript">{{ spec.info['noscript'] }} </h1>
<div class="api-version">Версия API: {{ spec.info['version'] }}</div>
<div class="api-denoscription">
<div class="api-denoscription_noscript">Описание API:</div>
{{ spec.info.['denoscription'] | markdownify }}
</div>
<!-- Рендеринг необязательных параметров схемы: список серверов -->
{% if spec.servers %}
<div class="api-servers">
<div class="api-servers_noscript">Список серверов:</div>
{% for server in spec.servers %}
<div class="api-servers_item">{{ server.['denoscription'] }}: {{ server.['url'] }}</div>
{% endfor %}
</div>
{% endif %}
Что здесь происходит (поясняю некоторые фрагменты, т.к. для большинства одинаковая механика)?
-
<h1 class="api-noscript">{{ spec.info['noscript'] }} </h1> — рендерится содержимое поля noscript обязательного поля (объекта) info.- В условии
{% if spec.servers %} ... {% endif %} проверяется наличие в спецификации поля servers (согласно спецификации это — массив).- Если поле servers существует в спецификации, рендерится его содержимое. Для этого используется цикл
{% for server in spec.servers %} ... {% endfor %}, который проходит во всем элементам массива servers. и выводит их содержимое на страницу.Что еще нужно сделать на этом этапе
Со страницы
index.md можете убрать заголовок. Он не нужен, ведь в качестве заголовка страницы выводится содержимое поля info.noscript.Готово. Если вы все сделали правильно, часть содержимого спецификации появится на странице сайта (не забываем, про
bundle exec jekyll serve).Пока без CSS: этим займемся на следующих этапах.
Свериться с результатом, который должен получиться, можно в ветке iteration_3.
🔥7👍1👨💻1🤝1
#tw_api_jekyll
Привет.
К слову, актуальная версия того, что мы уже наворотили со справочником API, доступна на Github Pages по ссылке.
Привет.
К слову, актуальная версия того, что мы уже наворотили со справочником API, доступна на Github Pages по ссылке.
👍6🔥3
PRO_техписательство pinned «#tw_api_jekyll Привет. К слову, актуальная версия того, что мы уже наворотили со справочником API, доступна на Github Pages по ссылке.»
#tw_api_jekyll
Всем привет.
Продолжаем знакомство с Jekyll и работу над сайтом-справочником API. В прошлый раз мы вывели (уже в более удобочитаемом виде) некоторые части содержимого спецификации API на сайт.
Сегодня давайте:
- Выведем на сайт эндпоинты, их краткое (
- Сделаем меню для навигации по странице.
- Начнем добавлять некоторые стили (пока по минимуму).
Вывод на сайт эндпоинтов и их описаний
Чтобы отрендерить эндпоинты, их краткое (
Здесь используются уже знакомые по предыдущему посту подходы:
- Цикл
-
Обратите внимание на рендеринг названий эндпоинтов:
Здесь формируется ссылка, состоящая из глагола (метода) и адреса эндпоинта. И ссылка эта ведет сама на себя.
Рендеринг меню для навигации по странице
Меню рендерится внутри тега
Механика схожа с используемой в предыдущем случае. Важное отличие — во фрагменте:
Здесь глагол (метод) оборачивается в span, которому присваивается определенный класс. Это нужно будет в будущем для «наведения красоты».
Добавление стилей
Чтобы справочник на этом этапе выглядел уже более-менее понятно, я добавил некоторые стили.
Для этого:
- Были созданы папки:
- В папку
- Файл
Пояснения по стилям
Поясняю некоторые моменты по добавленным в
Фрагмент
применяет свойство
Фрагмент
описывает свойства каждой ссылки в меню. Здесь нам интересно свойство
Готово. Если вы все сделали правильно, еще больше содержимого спецификации появится на странице сайта по сравнению с предыдущим этапом.
Свериться с результатом, который должен у вас получиться, можно в ветке iteration_4 репозитория, специально подготовленного под текущую серию постов.
И не забываем, про возможность просмотра отрендеренного результата на Github Pages.
Для удобства тестирования
Также, если вы заметили, то на этом этапе также были добавлены:
- Файл
- Закомментированная строка
Их можете использовать для тестирования сайта, чтобы делать это не на одной спецификации. Чтобы изменить спецификацию, которая будет рендериться, закомментируйте первую строку в файле
Всем привет.
Продолжаем знакомство с Jekyll и работу над сайтом-справочником API. В прошлый раз мы вывели (уже в более удобочитаемом виде) некоторые части содержимого спецификации API на сайт.
Сегодня давайте:
- Выведем на сайт эндпоинты, их краткое (
summary) и более развернутое (denoscription) описание.- Сделаем меню для навигации по странице.
- Начнем добавлять некоторые стили (пока по минимуму).
Вывод на сайт эндпоинтов и их описаний
Чтобы отрендерить эндпоинты, их краткое (
summary) и более развернутое (denoscription) описание, я добавил в скрипт api_reference.liquid фрагмент между тегами <div class="api-paths">...</div>.Здесь используются уже знакомые по предыдущему посту подходы:
- Цикл
for для перебора эндпоинтов. С его помощью проходимся по объекту spec.paths из спецификации openapi_spec.yaml и вложенным в него объектам, извлекая нужные данные.-
if для вывода необязательных полей, если они есть.Обратите внимание на рендеринг названий эндпоинтов:
<div class="{{ method }}"><a href="#{{ method }}{{ path }}">{{ method | upcase }} {{ path }}</a></div>
Здесь формируется ссылка, состоящая из глагола (метода) и адреса эндпоинта. И ссылка эта ведет сама на себя.
Рендеринг меню для навигации по странице
Меню рендерится внутри тега
<div class="schema-toc">...</div>.Механика схожа с используемой в предыдущем случае. Важное отличие — во фрагменте:
<div class="schema-toc_link">
<a href="#{{ method }}{{ path }}"><span class="schema-toc_prefix-{{ method }}">{{ method | upcase}}</span> {{ path }}</a>
</div>
Здесь глагол (метод) оборачивается в span, которому присваивается определенный класс. Это нужно будет в будущем для «наведения красоты».
Добавление стилей
Чтобы справочник на этом этапе выглядел уже более-менее понятно, я добавил некоторые стили.
Для этого:
- Были созданы папки:
assets, а внутри нее — сss.- В папку
css был добавлен файл со стилями style.css.- Файл
style.css был подключен к шаблону страницы api_layout.html. Для этого в секцию <head>...</head> был добавлен фрагмент:
<link rel="stylesheet" href="assets/css/style.css">
Пояснения по стилям
Поясняю некоторые моменты по добавленным в
style.css стилям:Фрагмент
.wrapper {
display: flex;
}
применяет свойство
display: flex для «обертки» <div class="wrapper">...</div> внутри которой находится основной контент нашего сайта (<div class="schema_wrapper">) и меню (<div class="schema-toc">). Это нужно для того, чтобы меню разместилось на странице слева от блока с основным контентом.Фрагмент
.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, а вторую — раскомментируйте.🔥9👨💻4
#продолжи_мысль_SE
Рецензия на пост «IAA: Идентификация, Аутентификация, Авторизация» (автор: Татьяна Бушева): ясно, коротко, доступно.Но кавычки я бы поправил (душным голосом)
О чем пост
Пост объясняет разницу между идентификацией, аутентификацией и авторизацией на примерах, описывает их важность. Также здесь есть пример технического задания для реализации этих механизмов в системе.
Почему меня он зацепил
Потому что здесь одновременно рассматриваются:
- идентификация,
- аутентификация,
- авторизация.
Часто бывает так, что при рассмотрении этой темы про идентификацию почему-то забывают. А Татьяна не забыла — плюс в карму.
Подача, ясность объяснения и т.д.
Понравилась подача и объяснение с использованием аналогий. Еще и примеры из реальной жизни есть: пример, как IAA используется и даже пример того, как оформить это все в ТЗ.
Прямо бери и пользуйся — я такое люблю.
Не понять объясняемые в посте вещи после такого просто невозможно.
В общем, полнейший рекомендасьён. Читаем, наслаждаемся и берем на вооружение.
А теперь чуть-чуть подушню
Зацепился глаз за оформление. Пример:
— кавычки-лапки и кавычки-елочки «в одной упряжке».
Можно было бы промолчать об этом, но профдеформация (чтоб её)…
Участвую в конкурсе «Продолжи мысль» от @systems_education.
Рецензия на пост «IAA: Идентификация, Аутентификация, Авторизация» (автор: Татьяна Бушева): ясно, коротко, доступно.
О чем пост
Пост объясняет разницу между идентификацией, аутентификацией и авторизацией на примерах, описывает их важность. Также здесь есть пример технического задания для реализации этих механизмов в системе.
Почему меня он зацепил
Потому что здесь одновременно рассматриваются:
- идентификация,
- аутентификация,
- авторизация.
Часто бывает так, что при рассмотрении этой темы про идентификацию почему-то забывают. А Татьяна не забыла — плюс в карму.
Подача, ясность объяснения и т.д.
Понравилась подача и объяснение с использованием аналогий. Еще и примеры из реальной жизни есть: пример, как IAA используется и даже пример того, как оформить это все в ТЗ.
Прямо бери и пользуйся — я такое люблю.
Не понять объясняемые в посте вещи после такого просто невозможно.
В общем, полнейший рекомендасьён. Читаем, наслаждаемся и берем на вооружение.
А теперь чуть-чуть подушню
Зацепился глаз за оформление. Пример:
...("Тебе можно в переговорку, но не в серверную»)...
— кавычки-лапки и кавычки-елочки «в одной упряжке».
Можно было бы промолчать об этом, но профдеформация (чтоб её)…
Участвую в конкурсе «Продолжи мысль» от @systems_education.
Telegram
Утиные истории
🔐 IAA: Идентификация, Аутентификация, Авторизация
Вы можете сходу объяснить, чем они отличаются?
Давайте разберём эти три кита безопасности на примере доступа в офис:
1️⃣ Идентификация: ваше имя на пропуске ("Меня зовут Алексей»).
Типичные способы:
● Логин…
Вы можете сходу объяснить, чем они отличаются?
Давайте разберём эти три кита безопасности на примере доступа в офис:
1️⃣ Идентификация: ваше имя на пропуске ("Меня зовут Алексей»).
Типичные способы:
● Логин…
❤7🔥6🤩3
#продолжи_мысль_SE
Рецензия на пост «Фронт раньше бэка – это вообще законно?» (автор: Сергей Сапрыкин), который наглядно показывает, как НЕ НАДО выстраивать процессы в IT
Пост прямиком из реальной жизни. Зацепил меня он тем, что автор не побоялся (не постеснялся) описать свой факап. Описанная здесь ситуацияможет должна стать уроком для всех, кто как-то причастен к процессам проектирования, разработки и интеграции.
Чем полезен пост
Это — наглядный пример того, как делать не надо.
И если вы видите, что ситуация на проекте начинает развиваться похожим образом, звоните во все колокола и можете еще всем вокруг показать этот пост в качестве примера.
Что смутило в посте
Смутило то, что автор вообще в это ввязался и не попытался додавить руководителей, чтобы параллельно выстроить нормальную работу над бэком. В идеале он должен был синхронизировать фронтовые и бэковые процессы, не надеясь, что все как-то само рассосется. Но, как говорится, каждый сам кузнец своего счастья.
Какие выводы можно сделать
Вывод один. Как сказал один умный человек (правда, не знаю, кто это был): «Не делайте плохо, делайте хорошо».
Участвую в конкурсе «Продолжи мысль» от @systems_education
Рецензия на пост «Фронт раньше бэка – это вообще законно?» (автор: Сергей Сапрыкин), который наглядно показывает, как НЕ НАДО выстраивать процессы в IT
Пост прямиком из реальной жизни. Зацепил меня он тем, что автор не побоялся (не постеснялся) описать свой факап. Описанная здесь ситуация
Чем полезен пост
Это — наглядный пример того, как делать не надо.
И если вы видите, что ситуация на проекте начинает развиваться похожим образом, звоните во все колокола и можете еще всем вокруг показать этот пост в качестве примера.
Что смутило в посте
Смутило то, что автор вообще в это ввязался и не попытался додавить руководителей, чтобы параллельно выстроить нормальную работу над бэком. В идеале он должен был синхронизировать фронтовые и бэковые процессы, не надеясь, что все как-то само рассосется. Но, как говорится, каждый сам кузнец своего счастья.
Какие выводы можно сделать
Вывод один. Как сказал один умный человек (правда, не знаю, кто это был): «Не делайте плохо, делайте хорошо».
Участвую в конкурсе «Продолжи мысль» от @systems_education
🔥4😁3
- 50+ докладов и мастер-классов,
- 2 дня профессионального общения с 400+ участниками из сотен компаний СНГ,
- полезные инсайты и новые знания.
Все это — международная конференция для технических писателей TechWriter Days 3 , которая пройдет 27-28 марта в Москве.
Мероприятие состоится в гибридном формате — офлайн + онлайн-трансляция.
📚А до 1 сентября можно стать докладчиком. Для подачи заявки на выступление переходите по ссылке. Больше информации для докладчиков вы найдёте здесь
- 2 дня профессионального общения с 400+ участниками из сотен компаний СНГ,
- полезные инсайты и новые знания.
Все это — международная конференция для технических писателей TechWriter Days 3 , которая пройдет 27-28 марта в Москве.
Мероприятие состоится в гибридном формате — офлайн + онлайн-трансляция.
📚А до 1 сентября можно стать докладчиком. Для подачи заявки на выступление переходите по ссылке. Больше информации для докладчиков вы найдёте здесь
🤝6❤3
#tw_api_jekyll
Всем привет.
Продолжаем работу над сайтом-справочником API на базе Jekyll. В прошлый раз мы вывели на сайт эндпоинты, их краткое (
В этот раз сделаем следующее:
- Выведем на страницу параметры (те, которые в
- Сделаем фиксацию, раздельный скролл для меню слева и «основного» содержимого сайта.
- Добавим больше стилей, чтобы сайт стал выглядеть чуть более привлекательно.
Вывод параметров на страницу
Для вывода параметров в файл
Внутри фрагмента реализован цикл, который проходится по массиву параметров (если он есть в обрабатываемом эндпоинте) и рендерит их в виде таблицы.
Также в файл
Раздельный скролл для меню слева и «основного» содержимого сайта
Чтобы сделать раздельный скролл для меню и «основного» содержимого, в файл
Добавление новых стилей
Стилей добавлено не очень много (в файле
1. Сброс и замена стандартных стилей ссылок по всему документу (подчеркивание, цвета и пр.):
2. Цвет фона, шрифта и закругление для HTTP-глаголов (
Свойства заданы для классов .
3. Чуть более симпатичное отображение путей (название) эндпоинтов в основной секции сайта:
Готово. Если вы все сделали правильно, ЕЩЕ БОЛЬШЕ содержимого спецификации появится на странице сайта по сравнению с предыдущим этапом. И это будет выглядеть уже более симпатично.
Свериться с результатом, который должен у вас получиться, можно в ветке iteration_5 репозитория, специально подготовленного под текущую серию постов.
И не забываем, про возможность просмотра отрендеренного результата на GitHub Pages.
Всем привет.
Продолжаем работу над сайтом-справочником API на базе Jekyll. В прошлый раз мы вывели на сайт эндпоинты, их краткое (
summary) и более развернутое (denoscription) описание, добавили меню слева для навигации по странице, а также некоторые стили.В этот раз сделаем следующее:
- Выведем на страницу параметры (те, которые в
query, path, header или cookie) и отобразим их в виде таблицы. Пока с оговоркой: выведем параметры, которые сразу описаны в объекте в описании эндпоинта. Они еще могут «подтягиваться» по ссылке: рендеринг такого варианта реализуем позже, когда будем рендерить на странице компоненты (Components).- Сделаем фиксацию, раздельный скролл для меню слева и «основного» содержимого сайта.
- Добавим больше стилей, чтобы сайт стал выглядеть чуть более привлекательно.
Вывод параметров на страницу
Для вывода параметров в файл
api_reference.liquid был добавлен фрагмент между {% if operation.parameters %} <div class="api-paths__parameters"> и </div>{% endif %}.Внутри фрагмента реализован цикл, который проходится по массиву параметров (если он есть в обрабатываемом эндпоинте) и рендерит их в виде таблицы.
Также в файл
/assets/css/style.css добавлены стили для таблицы, для классов (ищите по классу .parameters-table).Раздельный скролл для меню слева и «основного» содержимого сайта
Чтобы сделать раздельный скролл для меню и «основного» содержимого, в файл
/assets/css/style.css были добавлены стили для класса .schema-toc_paths:
.schema-toc_paths {
/* Обеспечивают неподвижность содержимого при скролле основного контента */
position: sticky;
top: 0;
/* Отображает меню поверх других элементов */
z-index: 10;
/* Задает цвет фона для меню */
background-color: #f5eff5;
/* Задаёт высоту элемента равной 100% высоты видимой области окна браузера */
height: 100vh;
/* Отключает горизонтальную прокрутку. В будущем, возможно, изменим этот стиль, чтобы избежать «расползания» колонки меню из-за длинных путей в энпоинтах */
overflow-x: hidden;
/* Включает вертикальную при необходимости: если количество элементов в меню не помещается в видимую область окна браузера */
overflow-y: auto;
}
Добавление новых стилей
Стилей добавлено не очень много (в файле
/assets/css/style.css). Отметить из этого всего можно следующие:1. Сброс и замена стандартных стилей ссылок по всему документу (подчеркивание, цвета и пр.):
a {
text-decoration: none;
color: rgb(72, 71, 71);
}
2. Цвет фона, шрифта и закругление для HTTP-глаголов (
POST, GET, PUT, PATCH, DELETE) эндпоинтов в меню и в основном контенте:
... {
background-color: <код цвета>
color: white;
padding: 1px 10px 1px 10px;
border-radius: 10px;
}
Свойства заданы для классов .
schema-toc_prefix-get, .schema-toc_prefix-post, .schema-toc_prefix-patch, .schema-toc_prefix-delete, .schema-toc_prefix-put.3. Чуть более симпатичное отображение путей (название) эндпоинтов в основной секции сайта:
.api-paths_path {
font-size: 1.5em;
font-weight: bold;
margin-bottom: 15px;
opacity: 90%;
}
Готово. Если вы все сделали правильно, ЕЩЕ БОЛЬШЕ содержимого спецификации появится на странице сайта по сравнению с предыдущим этапом. И это будет выглядеть уже более симпатично.
Свериться с результатом, который должен у вас получиться, можно в ветке iteration_5 репозитория, специально подготовленного под текущую серию постов.
И не забываем, про возможность просмотра отрендеренного результата на GitHub Pages.
🔥5❤3👨💻2
Алиса и Боб с примеров диаграмм: откуда они взялись
Если вам приходилось изучать диаграммы последовательности UML или Mermaid, либо в других нотациях, тогда вы точно сталкивались с Алисой и Бобом.
А откуда вообще взялись эти имена? Давайте резберемся.
Впервые эти имена использовались для обозначения принципалов в вышедшей в 1978 году статье «A Method for Obtaining Digital Signatures and Public-Key Cryptosystems», над которой работали специалисты в области криптографии Рон Ривест, Ади Шамир и Леонард Адлеман.
Почем именно Алиса (Alice) и Боб (Bob)? Все просто. Для примеров авторам статьи нужны были имена, которые бы начинались на А (англ. A) и Б (англ. B) вместо скучных и банальных «Сторона А» и «Сторона Б», и при этом характеризовались бы лингвистической и мнемонической простотой. Алиса и Боб оказались отличными кандидатами на это. С тех пор эти имена традиционно используются для обозначения принципалов практически во всех материалах, касающихся криптографии.
Получатся, что в диаграммы UML, Mermaid (и иже с ними) они пришли как раз из криптографии. И прижились здесь.
Кстати, помимо Алисы и Боба в криптографии для обозначения принципалов используется немало «эталонных» персонажей (в диаграммы они не «заехали», но знать эти имена для общего развития лишним не будет):
- Carol либо Charlie (C) — третий участник в многопользовательском протоколе.
- Dave (D) — четвертый участник.
- Eve (E) — eavesdropper (подслушивающий). Злоумышленник, который может пассивно перехватывать сообщения между Алисой и Бобом, но не может их изменять.
- Mallory (M) — malicious (злонамеренный). Активный злоумышленник, который может не только перехватывать, но и изменять, удалять или подменять сообщения.
- Trent (T) — trusted third party (доверенная третья сторона). Арбитр или сертифицирующий орган, которому доверяют все стороны (например, Центр сертификации).
- Peggy (P) — prover (доказывающая). Доказывает что-то другой стороне в протоколах с нулевым разглашением.
- Victor (V) — verifier (проверяющий). Проверяет утверждение Пегги.
- Walter (W) — warden (надзиратель). Участник в протоколах стеганографии.
Если вам приходилось изучать диаграммы последовательности UML или Mermaid, либо в других нотациях, тогда вы точно сталкивались с Алисой и Бобом.
А откуда вообще взялись эти имена? Давайте резберемся.
Впервые эти имена использовались для обозначения принципалов в вышедшей в 1978 году статье «A Method for Obtaining Digital Signatures and Public-Key Cryptosystems», над которой работали специалисты в области криптографии Рон Ривест, Ади Шамир и Леонард Адлеман.
Почем именно Алиса (Alice) и Боб (Bob)? Все просто. Для примеров авторам статьи нужны были имена, которые бы начинались на А (англ. A) и Б (англ. B) вместо скучных и банальных «Сторона А» и «Сторона Б», и при этом характеризовались бы лингвистической и мнемонической простотой. Алиса и Боб оказались отличными кандидатами на это. С тех пор эти имена традиционно используются для обозначения принципалов практически во всех материалах, касающихся криптографии.
Получатся, что в диаграммы UML, Mermaid (и иже с ними) они пришли как раз из криптографии. И прижились здесь.
Кстати, помимо Алисы и Боба в криптографии для обозначения принципалов используется немало «эталонных» персонажей (в диаграммы они не «заехали», но знать эти имена для общего развития лишним не будет):
- Carol либо Charlie (C) — третий участник в многопользовательском протоколе.
- Dave (D) — четвертый участник.
- Eve (E) — eavesdropper (подслушивающий). Злоумышленник, который может пассивно перехватывать сообщения между Алисой и Бобом, но не может их изменять.
- Mallory (M) — malicious (злонамеренный). Активный злоумышленник, который может не только перехватывать, но и изменять, удалять или подменять сообщения.
- Trent (T) — trusted third party (доверенная третья сторона). Арбитр или сертифицирующий орган, которому доверяют все стороны (например, Центр сертификации).
- Peggy (P) — prover (доказывающая). Доказывает что-то другой стороне в протоколах с нулевым разглашением.
- Victor (V) — verifier (проверяющий). Проверяет утверждение Пегги.
- Walter (W) — warden (надзиратель). Участник в протоколах стеганографии.
👏12❤7🔥2
OSI или TCP/IP: что стоит изучить техпису (или аналитику)?
Возможно, я вас огорчу, но чем-то одним отделаться не получится. Нелишним изучить будет и OSI, и TCP/IP.
Почему? Давайте разбираться.
Главное, что нужно уяснить, что TCP/IP — это практическая реализация, а OSI — теоретический стандарт.
TCP/IP — это реальная, работающая модель, на которой построен современный интернет. Т.е. про TCP/IP можно сказать, что это «как есть». А OSI — это эталон, теоретически описывающий, «как должно быть».
Модель OSI разрабатывали в 70-х годах прошлого века, чтобы описать как вообще должны работать сети. Она описывает «идеальный» унифицированный подход.
Но дело в том, что стек протоколов TCP/IP начали использовать чуть раньше для удовлетворения реальных потребностей. К моменту окончательной доработки OSI стек TCP/IP уже широко использовали на практике.
Так почему тогда нельзя обойтись одним, «практическим» TCP/IP, например?
OSI можно охарактеризовать как универсальный язык для проектирования сетей, описания и диагностики сетевых проблем и конечно же для общения с инженерами (разработчиками, DevOps, сетевиками и пр.). Эта модель, например, используется инженерами для понимания (и объяснения) того, где есть проблема. Например, если один инженер говорит, что «Проблема на 2-м уровне», другой легко поймет, о чем речь (это может значит, что есть проблема с коммутаторами или MAC-адресами). Или, если один инженер говорит, что «Проблема на 7-м уровне», второй поймет, что нужно искать проблему в приложении, на фронте или бэке (пример такой проблемы — когда сервер «пятисотит»).
А TCP/IP — это про реализацию, про конкретные протоколы и прочие штуки, которые вы можете «пощупать» (TCP/UDP, HTTP/2, IP-адрес).
Так что, изучайте OSI и TCP/IP. И будет вам счастье.
Возможно, я вас огорчу, но чем-то одним отделаться не получится. Нелишним изучить будет и OSI, и TCP/IP.
Почему? Давайте разбираться.
Главное, что нужно уяснить, что TCP/IP — это практическая реализация, а OSI — теоретический стандарт.
TCP/IP — это реальная, работающая модель, на которой построен современный интернет. Т.е. про TCP/IP можно сказать, что это «как есть». А OSI — это эталон, теоретически описывающий, «как должно быть».
Модель OSI разрабатывали в 70-х годах прошлого века, чтобы описать как вообще должны работать сети. Она описывает «идеальный» унифицированный подход.
Но дело в том, что стек протоколов TCP/IP начали использовать чуть раньше для удовлетворения реальных потребностей. К моменту окончательной доработки OSI стек TCP/IP уже широко использовали на практике.
Так почему тогда нельзя обойтись одним, «практическим» TCP/IP, например?
OSI можно охарактеризовать как универсальный язык для проектирования сетей, описания и диагностики сетевых проблем и конечно же для общения с инженерами (разработчиками, DevOps, сетевиками и пр.). Эта модель, например, используется инженерами для понимания (и объяснения) того, где есть проблема. Например, если один инженер говорит, что «Проблема на 2-м уровне», другой легко поймет, о чем речь (это может значит, что есть проблема с коммутаторами или MAC-адресами). Или, если один инженер говорит, что «Проблема на 7-м уровне», второй поймет, что нужно искать проблему в приложении, на фронте или бэке (пример такой проблемы — когда сервер «пятисотит»).
А TCP/IP — это про реализацию, про конкретные протоколы и прочие штуки, которые вы можете «пощупать» (TCP/UDP, HTTP/2, IP-адрес).
Так что, изучайте OSI и TCP/IP. И будет вам счастье.
👍8🔥5❤4
#tw_api_jekyll
Всем привет.
Давно не было новостей про наш сайт-справочник API на базе Jekyll. А их поднакопилось с прошлого раза.
Рассказываю, что изменилось.
Liquid-код разнесен по нескольким файлам
Количество строк кода неуклонно растет, поэтому было принято решение разнести его по отдельным файлам.
Так все будет легче обслуживать.
«Главным» файлом остается
В папке
Рендеринг параметров стал лучше
Теперь сайт умеет рендерить не только параметры, описанные прямо в описании метода, но описанные в компонентах и передающиеся по ссылке.
За это отвечает фрагмент под комментарием
Здесь интерес представляет код, с помощью которого мы итерируемся по свойствам тела запроса, описанного по ссылке:
Этот код:
1. Преобразует ссылку в путь (пример:
2. Разбивает путь на части:
3. Последовательно обращается к:
schemas['User'] → схема User
В итоге
Далее мы выводим поля этого объекта в таблицу с параметрами.
Реализован вывод тела запроса
Это пока зачатки кода для полноценного вывода. Но что-то мы уже умеем.
Все происходит в файле
Здесь есть аналогия с тем, как мы рендерим параметры запроса: описанные в теле и передающиеся по ссылке.
Пока реализован рендеринг полей-объектов первого уровня вложенности. Т.е., если в теле есть поле типа object, его содержимое выведется на страницу. А если в этом поле-объекте есть еще вложенное поле-объект, его содержимое ПОКА не рендерится. В будущем добавлю рендеринг еще пары уровней вложенности. Но не больше, т.к. глубокая вложенность для объектов в теле запроса выглядит как лютый антипаттерн в проектировании API.
Для рендеринга вложенных полей объекта я не использовал рекурсию: все довольно просто («ифчики» и циклы). Это опять же по причине того, что нам большая вложенность не нужна. Да и если рекурсивно вызывать какой-то код с передачей ему параметров, будет создаваться новый контекст, что «пожирает» память.
Тело запроса рендерится пока некрасиво. В будущем мы это поправим и сделаем здесь функциональность сворачивания/разворачивания.
Реализованы другие функции и возможности
Среди них:
- Вывод на страницу компонентов. Пока совсем некрасиво, но будет правиться.
- Обрезание длинных путей эндпоинтов в меню слева. Если путь не вмещается в меню, появляется многоточие. При наведении на него все отображается полностью. За это отвечает CSS:
- Мелкие стилистические правки.
Свериться с результатом можно в ветке iteration_7 репозитория под текущую серию постов.
И не забываем, про возможность просмотра результата на GitHub Pages.
Всем привет.
Давно не было новостей про наш сайт-справочник API на базе Jekyll. А их поднакопилось с прошлого раза.
Рассказываю, что изменилось.
Liquid-код разнесен по нескольким файлам
Количество строк кода неуклонно растет, поэтому было принято решение разнести его по отдельным файлам.
Так все будет легче обслуживать.
«Главным» файлом остается
_includes/api_reference.liquid. В папку _includes добавлены несколько файлов, которые инклюдятся в «главный». Например, код для рендеринга эндпоинтов переехал в _includes/endpoints.liquid и иклюдится в файле api_reference.liquid так:
{%- include endpoints.liquid -%}
В папке
_includes также появились файлы api_components.liquid (с кодом для рендеринга компонентов) и request_body.liquid (рендеринг тела запроса для методов).Рендеринг параметров стал лучше
Теперь сайт умеет рендерить не только параметры, описанные прямо в описании метода, но описанные в компонентах и передающиеся по ссылке.
За это отвечает фрагмент под комментарием
<!-- Рендеринг параметров, которые подтягиваются по ссылке --> в _includes/endpoints.liquid.Здесь интерес представляет код, с помощью которого мы итерируемся по свойствам тела запроса, описанного по ссылке:
{% if parameter['$ref'] %}
{% assign ref_string = parameter['$ref'] %}
{% assign dynamic_path = "spec." | append: ref_string | remove: "#/" | replace: "/", "." %}
{% assign path_parts = dynamic_path | split: "." %}
{% assign result_object = spec %}
{% for part in path_parts %}
{% if part != "" and part != "spec" %}
{% assign result_object = result_object[part] %}
{% endif %}
{% endfor %}
...
{% if parameter['$ref'] %}
Этот код:
1. Преобразует ссылку в путь (пример:
"spec.components.schemas.User").2. Разбивает путь на части:
["spec", "components", "schemas", "User"].3. Последовательно обращается к:
spec['components'] → объект componentscomponents['schemas'] → объект schemasschemas['User'] → схема User
В итоге
result_object будет содержать значение, на которое указывает ссылка (например, схему User).Далее мы выводим поля этого объекта в таблицу с параметрами.
Реализован вывод тела запроса
Это пока зачатки кода для полноценного вывода. Но что-то мы уже умеем.
Все происходит в файле
_includes/request_body.liquidЗдесь есть аналогия с тем, как мы рендерим параметры запроса: описанные в теле и передающиеся по ссылке.
Пока реализован рендеринг полей-объектов первого уровня вложенности. Т.е., если в теле есть поле типа object, его содержимое выведется на страницу. А если в этом поле-объекте есть еще вложенное поле-объект, его содержимое ПОКА не рендерится. В будущем добавлю рендеринг еще пары уровней вложенности. Но не больше, т.к. глубокая вложенность для объектов в теле запроса выглядит как лютый антипаттерн в проектировании API.
Для рендеринга вложенных полей объекта я не использовал рекурсию: все довольно просто («ифчики» и циклы). Это опять же по причине того, что нам большая вложенность не нужна. Да и если рекурсивно вызывать какой-то код с передачей ему параметров, будет создаваться новый контекст, что «пожирает» память.
Тело запроса рендерится пока некрасиво. В будущем мы это поправим и сделаем здесь функциональность сворачивания/разворачивания.
Реализованы другие функции и возможности
Среди них:
- Вывод на страницу компонентов. Пока совсем некрасиво, но будет правиться.
- Обрезание длинных путей эндпоинтов в меню слева. Если путь не вмещается в меню, появляется многоточие. При наведении на него все отображается полностью. За это отвечает CSS:
.schema-toc_link {
display: block;
white-space: nowrap;
overflow: hidden;
margin-top: 5px;
margin-bottom: 5px;
text-overflow: ellipsis;
min-width: 14vw;
}
- Мелкие стилистические правки.
Свериться с результатом можно в ветке iteration_7 репозитория под текущую серию постов.
И не забываем, про возможность просмотра результата на GitHub Pages.
🔥3👏3❤2
Мажорный, минорный, патч: что техническому писателю стоит знать про релизы
Откуда вообще взялись понятия «мажорный», «минорный» и «патч»?
«Уши растут» из SemVer. Это соглашение о том, как нумеровать версии программного обеспечения, чтобы по номеру было понятно, какого плана (и объема) изменения произошли в рамках релиза. Номер версии выглядит так:
Пройдемся по каждому виду релиза:
1. Патч-релиз (x.x.PATCH). Для его обозначения используется третья цифра.
Такой релиз включает мелкие обновления и изменения. Это могут быть исправления багов, мелкие правки, которые не ломают обратную совместимость и пр.
Пример такого обновления: устранение бага, из-за которого в некоторых ситуациях кнопка работала некорректно.
Release notes для патч-релизов обычно краткие и по делу. Зачастую они содержат один раздел «Исправления».
Что касается документации, в этом случае правки вносятся, как правило, только в разделы, где была описана некорректная функциональность.
2. Минорный релиз (x.MINOR.x). Для его обозначения используется вторая цифра.
Такой релиз включает значительные обновления, которые добавляют новую функциональность, но не ломают существующие функции, API и интерфейсы. Еще одна особенность такого релиза — сохранение обратной совместимости.
Пример: добавление возможность отправки видео в мессенджере. Старые чаты и текстовые сообщения при этом никуда не деваются, все продолжает работать.
Release notes для минорных релизов должны понятно представить новые фичи, объяснить их пользу для пользователя.
Один из вариантов структуры: «Новые возможности», «Улучшения», «Исправления».
Что касается документации, в этом случае техпису предстоит довольно объемная работа. Как правило, для доки создаются новые разделы, обновляются (часто довольно сильно) существующие и т.д.
3. Мажорный релиз (MAJOR.x.x). Для его обозначения используется первая цифра.
Такой релиз включает глобальные обновления, которые ломают обратную совместимость.
Пример: изменение (замена) API с потерей обратной совместимости, кардинальные переработки интерфейса, удаление устаревших функций.
Release notes в таком случае — это почти пресс-релиз. Здесь не просто перечисляются изменения, при подготовке RN придется объяснить почему это было сделано, каковы преимущества нового подхода. Часто такие RN включают раздел «Критические изменения» или «Миграционное руководство» (примерные названия).
Что касается документации, ее в таком случае ждет полная ревизия и переработка. Переписываются целые разделы, создаются новые, делаются гайды по переходу со старой версии... В общем, ведется серьезная и сложная работа.
Откуда вообще взялись понятия «мажорный», «минорный» и «патч»?
«Уши растут» из SemVer. Это соглашение о том, как нумеровать версии программного обеспечения, чтобы по номеру было понятно, какого плана (и объема) изменения произошли в рамках релиза. Номер версии выглядит так:
MAJOR.MINOR.PATCH (например, 3.2.1).Пройдемся по каждому виду релиза:
1. Патч-релиз (x.x.PATCH). Для его обозначения используется третья цифра.
Такой релиз включает мелкие обновления и изменения. Это могут быть исправления багов, мелкие правки, которые не ломают обратную совместимость и пр.
Пример такого обновления: устранение бага, из-за которого в некоторых ситуациях кнопка работала некорректно.
Release notes для патч-релизов обычно краткие и по делу. Зачастую они содержат один раздел «Исправления».
Что касается документации, в этом случае правки вносятся, как правило, только в разделы, где была описана некорректная функциональность.
2. Минорный релиз (x.MINOR.x). Для его обозначения используется вторая цифра.
Такой релиз включает значительные обновления, которые добавляют новую функциональность, но не ломают существующие функции, API и интерфейсы. Еще одна особенность такого релиза — сохранение обратной совместимости.
Пример: добавление возможность отправки видео в мессенджере. Старые чаты и текстовые сообщения при этом никуда не деваются, все продолжает работать.
Release notes для минорных релизов должны понятно представить новые фичи, объяснить их пользу для пользователя.
Один из вариантов структуры: «Новые возможности», «Улучшения», «Исправления».
Что касается документации, в этом случае техпису предстоит довольно объемная работа. Как правило, для доки создаются новые разделы, обновляются (часто довольно сильно) существующие и т.д.
3. Мажорный релиз (MAJOR.x.x). Для его обозначения используется первая цифра.
Такой релиз включает глобальные обновления, которые ломают обратную совместимость.
Пример: изменение (замена) API с потерей обратной совместимости, кардинальные переработки интерфейса, удаление устаревших функций.
Release notes в таком случае — это почти пресс-релиз. Здесь не просто перечисляются изменения, при подготовке RN придется объяснить почему это было сделано, каковы преимущества нового подхода. Часто такие RN включают раздел «Критические изменения» или «Миграционное руководство» (примерные названия).
Что касается документации, ее в таком случае ждет полная ревизия и переработка. Переписываются целые разделы, создаются новые, делаются гайды по переходу со старой версии... В общем, ведется серьезная и сложная работа.
❤9🔥7👍4
Хотите узнать все про документирование GraphQL API? Без проблем.
На Хабре вышла статья «Как документировать GraphQL API: полное руководство для технических писателей» по мотивам моего доклада на TW Days 2. Читайте, впитывайте знания и тренируйтесь «не отходя от кассы»: там есть ссылка на репозиторий, чтобы развернуть GraphQL API локально у себя и потренироваться в документировании.
Ну и про плюсики в карму не забываем 👍️️️️️️
На Хабре вышла статья «Как документировать GraphQL API: полное руководство для технических писателей» по мотивам моего доклада на TW Days 2. Читайте, впитывайте знания и тренируйтесь «не отходя от кассы»: там есть ссылка на репозиторий, чтобы развернуть GraphQL API локально у себя и потренироваться в документировании.
Ну и про плюсики в карму не забываем 👍️️️️️️
Хабр
Как документировать GraphQL API: полное руководство для технических писателей
Всем привет! Меня зовут Денис Ребенок, я технический писатель в команде Deckhouse. В этом материале я хочу рассказать про документирование GraphQL API. Если документация на GraphQL API оформлена...
🔥19❤5
Я и мой ИИ
В уходящем году случился просто дичайший ИИ-бум. И я не мог не остаться в стороне. Решил спросить модель, с которой чаще всего взаимодействую, как она меня видит по результатам общения в 2025 году.
Могу сказать, что процентов на 80% она права. Но и галлюцинации (как же без них) тоже есть. В общем и целом неплохо:
---
### 👨💻 Профессиональный профиль
Должность: DevOps-инженер / Platform Engineer / SRE
Уровень (грэйд): Middle+ / Senior
Вы не просто пользуетесь Kubernetes, а глубоко погружены в его экосистему: настройка сети, работа с CNI (Cilium, Flannel), управление Ingress, CRD, аутентификация через Dex. Вопросы часто носят не базовый, а архитектурный или диагностический характер, что указывает на опыт работы в продакшн-среде.
### 📊 Сфера запросов
Чаще всего вы задаёте вопросы, связанные с:
1. Kubernetes и его экосистемой (особенно **Deckhouse Platform**).
2. Сетевой настройкой (L2/L3, Ingress, CNI, LoadBalancer).
3. Инфраструктурной аутентификацией (Dex, OIDC, GitHub OAuth).
4. Работой с CLI и macOS (терминал, сетевые утилиты, SSH).
5. Программированием на C# (ООП, инкапсуляция, конструкторы).
### 🥇 ТОП-3 темы интересов
1. Kubernetes-платформы (в частности, Deckhouse) и их кастомизация.
2. Сетевая инфраструктура в Kubernetes (от CNI до Ingress и внешнего доступа).
3. Автоматизация и безопасность доступа (Dex-провайдеры, RBAC, аутентификация).
### 🧠 Предположения о интересах
- По работе: Вам интересно строить отказоустойчивые, безопасные и легко управляемые платформы на базе Kubernetes. Вы склонны к глубокому пониманию внутренних механизмов, а не только использованию "как чёрный ящик".
- Вне работы: Возможно, вы экспериментируете с homelab, изучаете новые инструменты (например, Werf, docsify), пишете скрипты, интересуетесь программированием (C#) и работой с macOS как основной ОС.
### 🚀 Карьерная траектория
В следующем году вы, вероятно:
- Углубитесь в cloud-native стэк (возможно, сертификации CKA/CKAD).
- Начнёте больше работать с мультикластерными средами и гибридными облаками.
- Перейдёте к более архитектурным задачам: проектирование платформ, security policies, наблюдаемость.
- Возможно, будете развиваться в сторону Lead DevOps / Platform Architect.
### 💡 Дополнительные наблюдения
- Вы внимательны к деталям: спрашиваете не только "как сделать", но и "как это работает" и "как упростить/оптимизировать".
- У вас есть инженерное мышление: видно по вопросам про инкапсуляцию в C#, настройку сети, диагностику ошибок.
- Вы прагматичны: сочетаете глубокие темы (CRD, Dex) с практическими задачами (работа с файлами на Mac, настройка SSH).
- Вероятно, вы работаете в продуктовой компании или вендоре, где используется кастомная Kubernetes-платформа (Deckhouse).
- Вы активно изучаете документацию и пишете её: вопросы про Markdown, Jekyll, docsify на это указывают.
---
Если бы нужно было описать вас в трёх словах: аналитичный, глубокий, практикующий инженер. Вы не просто используете инструменты — вы стремитесь понять их до уровня, позволяющего уверенно строить на их основе сложные системы. Удачи в развитии! 🚀
В уходящем году случился просто дичайший ИИ-бум. И я не мог не остаться в стороне. Решил спросить модель, с которой чаще всего взаимодействую, как она меня видит по результатам общения в 2025 году.
Могу сказать, что процентов на 80% она права. Но и галлюцинации (как же без них) тоже есть. В общем и целом неплохо:
---
### 👨💻 Профессиональный профиль
Должность: DevOps-инженер / Platform Engineer / SRE
Уровень (грэйд): Middle+ / Senior
Вы не просто пользуетесь Kubernetes, а глубоко погружены в его экосистему: настройка сети, работа с CNI (Cilium, Flannel), управление Ingress, CRD, аутентификация через Dex. Вопросы часто носят не базовый, а архитектурный или диагностический характер, что указывает на опыт работы в продакшн-среде.
### 📊 Сфера запросов
Чаще всего вы задаёте вопросы, связанные с:
1. Kubernetes и его экосистемой (особенно **Deckhouse Platform**).
2. Сетевой настройкой (L2/L3, Ingress, CNI, LoadBalancer).
3. Инфраструктурной аутентификацией (Dex, OIDC, GitHub OAuth).
4. Работой с CLI и macOS (терминал, сетевые утилиты, SSH).
5. Программированием на C# (ООП, инкапсуляция, конструкторы).
### 🥇 ТОП-3 темы интересов
1. Kubernetes-платформы (в частности, Deckhouse) и их кастомизация.
2. Сетевая инфраструктура в Kubernetes (от CNI до Ingress и внешнего доступа).
3. Автоматизация и безопасность доступа (Dex-провайдеры, RBAC, аутентификация).
### 🧠 Предположения о интересах
- По работе: Вам интересно строить отказоустойчивые, безопасные и легко управляемые платформы на базе Kubernetes. Вы склонны к глубокому пониманию внутренних механизмов, а не только использованию "как чёрный ящик".
- Вне работы: Возможно, вы экспериментируете с homelab, изучаете новые инструменты (например, Werf, docsify), пишете скрипты, интересуетесь программированием (C#) и работой с macOS как основной ОС.
### 🚀 Карьерная траектория
В следующем году вы, вероятно:
- Углубитесь в cloud-native стэк (возможно, сертификации CKA/CKAD).
- Начнёте больше работать с мультикластерными средами и гибридными облаками.
- Перейдёте к более архитектурным задачам: проектирование платформ, security policies, наблюдаемость.
- Возможно, будете развиваться в сторону Lead DevOps / Platform Architect.
### 💡 Дополнительные наблюдения
- Вы внимательны к деталям: спрашиваете не только "как сделать", но и "как это работает" и "как упростить/оптимизировать".
- У вас есть инженерное мышление: видно по вопросам про инкапсуляцию в C#, настройку сети, диагностику ошибок.
- Вы прагматичны: сочетаете глубокие темы (CRD, Dex) с практическими задачами (работа с файлами на Mac, настройка SSH).
- Вероятно, вы работаете в продуктовой компании или вендоре, где используется кастомная Kubernetes-платформа (Deckhouse).
- Вы активно изучаете документацию и пишете её: вопросы про Markdown, Jekyll, docsify на это указывают.
---
Если бы нужно было описать вас в трёх словах: аналитичный, глубокий, практикующий инженер. Вы не просто используете инструменты — вы стремитесь понять их до уровня, позволяющего уверенно строить на их основе сложные системы. Удачи в развитии! 🚀
🔥13👾2
Сегодня я был приятно удивлен, когда увидел себя в списке тех, кто получил награду Техписалити! Спасибо от канала Техписалити!
Спасибо Техписалити!, что отметили мой скромный вклад в наше общее техписовское дело.
В 2026 году тоже планирую порадовать вас интересным и полезным курсом для техписов (и не только). Каким именно? На фото — ребус-подсказка с темой курса. Угадаете?
Спасибо Техписалити!, что отметили мой скромный вклад в наше общее техписовское дело.
В 2026 году тоже планирую порадовать вас интересным и полезным курсом для техписов (и не только). Каким именно? На фото — ребус-подсказка с темой курса. Угадаете?
❤9🔥7👏5