Моя статья «Документирование HTTP API (и не только) с Foliant», написанная по мотивам доклада на TWD1, попала в шорт-лист «Технотекста-7». Правда, категории про техническую документацию в этом году не было. Но, что есть, то есть.
В общем, вы знаете, что делать.
https://habr.com/ru/companies/habr/articles/906136/

Спите? Ну тогда просыпайтесь!

Я наконец-то сделал это, переформатировал и опубликовал Курс по проектированию и документированию API в виде сайта на Github Pages.

Если вы до этого момента сомневались, стоит ли проходить, хватит сомневаться. Кликайте сюда и проходите курс.

Нашел в закромах

А ведь я когда-то (во времена фрилансерства) даже участвовал в «битве Главреда» (да-да, того самого, «всея руси» который, на букву Иль...хов). Выиграть не получилось. Но опыт был интересный.

Почему я тогда ввязался в это? В тот момент работал с клиентом, который продвигал услуги по защите авторских прав с упором именно на IT. А тут как раз и битва на эту тему нарисовалась. «А почему бы и нет?» — подумал я.

В общем, результат по ссылке.

О сколько нам открытий чудных... Или передать все эти ваши Террабайты иногда быстрее с помощью грузовика

Читаю сейчас широко известную книгу про сети. И с удивлением для себя обнаружил, что большие объемы информации быстрее (не всегда, а в определенных случаях, конечно же) быстрее передать с помощью… грузовика. И даже сервис есть такой у Amazon.

А я как-то и не задумывался о том, что так можно было.

UPD. Сервис, оказывается уже закрыли (но другие альтернативы остались). Спасибо подписчику за наводку 👍.

Знания лишними не бывают. Особенно, когда они про популярный SSG

А давайте замутим небольшую серию постов про Jekyll и Liquid.

Погрузимся в это все (совсем неглубоко), конечно же, на практике: сделаем своими руками страничку с простым генератором справочника API из OpenAPI-спецификации. А дальше вы сможете его доработать под свои нужды, если захотите.

Вы в в деле?

Если в деле, ставьте под постом 🔥 (и друзей своих зовите, кому это может быть интересно).
Если нет — ставьте 👀.

#tw_api_jekyll

Привет, как договорились выше, начинаем знакомство с Jekyll и Liquid на практике. Это и серия других постов по теме будут помечены тегом #tw_api_jekyll. В рамках серии постов мы попробуем наладить сборку сайта-справочника API из спецификации в формате OpenAPI.

Сегодня мы подготовим «почву» для нашего справочника.
Для этого выполните следующее:

1. Установите себе на компьютер Jekyll и все зависимости по инструкции для вашей ОС со страницы Installation документации этого SSG (приобнял пользователей Windows — у вас самая длинная инструкция ).

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 и спецификацию, из которой он будет собираться.

#tw_api_jekyll

Привет. Продолжаем знакомство с Jekyll. В прошлый раз мы «подготовили почву» для нашего сайта-справочника.

Сегодня:

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

1. Добавление шаблона

Чтобы добавить шаблон для нашего сайта, сделайте следующее:

1.1. Создайте в корне директории с сайтом папку _layouts. Именно в ней по умолчанию Jekyll ищет шаблоны для страниц сайта.

1.2. Создайте в этой папке файл api_layout.html со следующим содержимым:

<!doctype html>
<html lang="ru">
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
  </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 репозитория, специально подготовленного под текущую серию постов.

#продолжи_мысль_SE

Зачем админ просит публичный ключ. Или что происходит при подключении к серверу по SSH

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

А зачем вообще нужен этот ключ и что происходит, когда мы пытаемся подключиться к серверу по SSH? Давайте разберемся (без захода в дебри).

Публичный и приватный ключ

Публичный ключ SSH (пример: user_rsa.pub) всегда существует в паре с приватным ключом, который носит такое же название, но не имеет расширения .pub (для нашего примера — user_rsa). Без приватного ключа публичный будет бесполезным.
И здесь важно запомнить: никому не передавайте свой приватный ключ. А публичный можете отправлять по запросу без проблем.

Зачем админу ваш публичный ключ

После получения публичного ключа админ помещает его в файл ~/.ssh/authorized_keys на сервере. И после этого вы можете подключаться к серверу по SSH.

А подключение происходит так (при условии, что оно не первое, про особенности первого — ниже):

1. Вы вводите в консоли команду для подключения к серверу (например, ssh [email protected]).
2. Сервер находит ваш публичный ключ в ~/.ssh/authorized_keys.
3. Сервер генерирует число, шифрует его с использованием вашего публичного ключа (генерирует challenge) и отправляет challenge в ответ вашему компьютеру.
4. Установленный на вашем компьютере SSH-агент расшифровывает с его помощью приватного ключа полученный challenge. Затем он создает подпись (которая содержит хеш от расшифрованного числа и данные сессии) и отправляет ее серверу.
5. Получив подпись, сервер сверяет ее с подписью, вычисленной локально с помощью публичного ключа (она тоже содержит хеш от числа и данные сессии).
6. Если подписи совпали, сервер разрешает доступ.

Этот процесс описан на диаграмме, прикрепленной к посту.

Если вы подключаетесь к серверу впервые

В этом случае после ввода в консоли команды для подключения к серверу и отправки запроса, сервер предъявляет в ответ свой публичный ключ (fingerprint). Получив его, компьютер спрашивает, добавить ли в доверенные. При положительном ответе fingerprint сервера добавляется в known_hosts на вашем компьютере. И теперь все работает, как описано выше (при запросе подключения к серверу он предъявляет свой fingerprint, чтобы подтвердить, что это реально он).

Почему публичный ключ, а не логин и пароль

Вариант с публичным ключом считается более безопасным.
При использовании логина и пароля последний передается по сети. А значит, есть вероятность его компрометации в случае перехвата злоумышленниками. Конечно, полностью отказываться от этого способа не стоит. Если вы, к примеру, работаете в приватной сети, изолированной от внешнего мира, логин и пароль — вполне ОК. Если же вы подключаетесь к серверу через публичную сеть, использование публичного и приватного ключей — must have.

Можно ли расшифровать число, отправляемое сервером с помощью публичного ключа

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

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

Участвую в конкурсе «Продолжи мысль» от @systems_education

#tw_api_jekyll

Всем привет.
Продолжаем знакомство с 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-title">{{ spec.info['title'] }} </h1>
  <div class="api-version">Версия API: {{ spec.info['version'] }}</div>
  <div class="api-description">
    <div class="api-description_title">Описание API:</div>
    {{ spec.info.['description'] | markdownify }}
  </div>
  <!-- Рендеринг необязательных параметров схемы: список серверов -->
  {% if spec.servers %}
  <div class="api-servers">
    <div class="api-servers_title">Список серверов:</div>
    {% for server in spec.servers %}
    <div class="api-servers_item">{{ server.['description'] }}: {{ server.['url'] }}</div>
    {% endfor %}
  </div>
  {% endif %}

Что здесь происходит (поясняю некоторые фрагменты, т.к. для большинства одинаковая механика)?

- <h1 class="api-title">{{ spec.info['title'] }} </h1> — рендерится содержимое поля title обязательного поля (объекта) info.
- В условии {% if spec.servers %} ... {% endif %} проверяется наличие в спецификации поля servers (согласно спецификации это — массив).
- Если поле servers существует в спецификации, рендерится его содержимое. Для этого используется цикл {% for server in spec.servers %} ... {% endfor %}, который проходит во всем элементам массива servers. и выводит их содержимое на страницу.

Что еще нужно сделать на этом этапе

Со страницы index.md можете убрать заголовок. Он не нужен, ведь в качестве заголовка страницы выводится содержимое поля info.title.

Готово. Если вы все сделали правильно, часть содержимого спецификации появится на странице сайта (не забываем, про bundle exec jekyll serve).
Пока без CSS: этим займемся на следующих этапах.

Свериться с результатом, который должен получиться, можно в ветке iteration_3.

#tw_api_jekyll

Привет.
К слову, актуальная версия того, что мы уже наворотили со справочником API, доступна на Github Pages по ссылке.

#tw_api_jekyll

Всем привет.
Продолжаем знакомство с Jekyll и работу над сайтом-справочником API. В прошлый раз мы вывели (уже в более удобочитаемом виде) некоторые части содержимого спецификации API на сайт.

Сегодня давайте:

- Выведем на сайт эндпоинты, их краткое (summary) и более развернутое (description) описание.
- Сделаем меню для навигации по странице.
- Начнем добавлять некоторые стили (пока по минимуму).

Вывод на сайт эндпоинтов и их описаний

Чтобы отрендерить эндпоинты, их краткое (summary) и более развернутое (description) описание, я добавил в скрипт 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, а вторую — раскомментируйте.

#продолжи_мысль_SE


Рецензия на пост «IAA: Идентификация, Аутентификация, Авторизация» (автор: Татьяна Бушева): ясно, коротко, доступно. Но кавычки я бы поправил (душным голосом)

О чем пост

Пост объясняет разницу между идентификацией, аутентификацией и авторизацией на примерах, описывает их важность. Также здесь есть пример технического задания для реализации этих механизмов в системе.

Почему меня он зацепил

Потому что здесь одновременно рассматриваются:

- идентификация,
- аутентификация,
- авторизация.

Часто бывает так, что при рассмотрении этой темы про идентификацию почему-то забывают. А Татьяна не забыла — плюс в карму.

Подача, ясность объяснения и т.д.

Понравилась подача и объяснение с использованием аналогий. Еще и примеры из реальной жизни есть: пример, как IAA используется и даже пример того, как оформить это все в ТЗ.
Прямо бери и пользуйся — я такое люблю.
Не понять объясняемые в посте вещи после такого просто невозможно.

В общем, полнейший рекомендасьён. Читаем, наслаждаемся и берем на вооружение.

А теперь чуть-чуть подушню

Зацепился глаз за оформление. Пример:

...("Тебе можно в переговорку, но не в серверную»)...

— кавычки-лапки и кавычки-елочки «в одной упряжке».

Можно было бы промолчать об этом, но профдеформация (чтоб её)…

Участвую в конкурсе «Продолжи мысль» от @systems_education.

#продолжи_мысль_SE


Рецензия на пост «Фронт раньше бэка – это вообще законно?» (автор: Сергей Сапрыкин), который наглядно показывает, как НЕ НАДО выстраивать процессы в IT


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

Чем полезен пост

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

Что смутило в посте

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

Какие выводы можно сделать

Вывод один. Как сказал один умный человек (правда, не знаю, кто это был): «Не делайте плохо, делайте хорошо».


Участвую в конкурсе «Продолжи мысль» от @systems_education

- 50+ докладов и мастер-классов,
- 2 дня профессионального общения с 400+ участниками из сотен компаний СНГ,
- полезные инсайты и новые знания.

Все это — международная конференция для технических писателей TechWriter Days 3 , которая пройдет 27-28 марта в Москве.

Мероприятие состоится в гибридном формате — офлайн + онлайн-трансляция.

📚А до 1 сентября можно стать докладчиком. Для подачи заявки на выступление переходите по ссылке. Больше информации для докладчиков вы найдёте здесь

#tw_api_jekyll

Всем привет.
Продолжаем работу над сайтом-справочником API на базе Jekyll. В прошлый раз мы вывели на сайт эндпоинты, их краткое (summary) и более развернутое (description) описание, добавили меню слева для навигации по странице, а также некоторые стили.

В этот раз сделаем следующее:

- Выведем на страницу параметры (те, которые в 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.

Алиса и Боб с примеров диаграмм: откуда они взялись

Если вам приходилось изучать диаграммы последовательности 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 (надзиратель). Участник в протоколах стеганографии.