#apidocs
Привет.
Продолжаем курс по проектированию и документированию API.
В прошлый раз мы собрали и задеплоили сайт-справочник.
Но он с дефолтными настройками. А ведь, наверняка вам захочется его кастомизировать (поменять цвета, размеры элементов, убрать какую-то информацию, добавить JS, скрипты и пр.). Все это реально: в репозитории со стартерпаком, который мы использовали на прошлом уроке, есть все необходимое для кастомизации сайта:
1. Папка
2. Папка
Досконально разбираться что за что отвевает в этих папках не будем, при желании можете сделать это самостоятельно. С
Давайте для примера внесем небольшие изменения в наш сайт, чуть-чуть кастомизировав его: изменим цвет подложки левой части сайта (где расположен список методов и ссылки на них).
Через инструменты разработчика модно увидеть, что левая часть сайта имеет CSS-класс
Для этого в файле
Я изменил значение переменной и цвет применился для подложки левой части сайта, а также для поля ввода формы поиска по сайту (т.к. он задается через ту же переменную
После внесения изменений не забудьте пересобрать сайт, чтобы увидеть результат.
Теперь вы знаете, как кастомизировать сайт-справочник, собранный с помощью
В следующий раз разберемся, как документировать API с помощью
Привет.
Продолжаем курс по проектированию и документированию API.
В прошлый раз мы собрали и задеплоили сайт-справочник.
Но он с дефолтными настройками. А ведь, наверняка вам захочется его кастомизировать (поменять цвета, размеры элементов, убрать какую-то информацию, добавить JS, скрипты и пр.). Все это реально: в репозитории со стартерпаком, который мы использовали на прошлом уроке, есть все необходимое для кастомизации сайта:
1. Папка
slate_shards/basic — здесь хранится шаблон страницы сайта-справочника, JS-скрипты, CSS-файлы и картинки, которые использует бэкенд Slate из состава Foliant для сборки сайта. Т.е. отсюда можно управлять всем, скажем так «фронтендом», нашего справочника.2. Папка
widdershins_templates — здесь хранятся шаблоны, в соответствии с которыми происходит преобразование OpenAPI-спецификации в Markdown, который потом отдается бэкенду Slate для генерации сайта.Досконально разбираться что за что отвевает в этих папках не будем, при желании можете сделать это самостоятельно. С
slate_shards/basic все понятно: открываем собранный сайт, открываем инструменты разработчика в браузере и изучаем селекторы элементов страницы, после чего можно влиять на них посредствам содержимого папки. С шаблонами widdershins_templates поможет разобраться официальная документация Widdershins.Давайте для примера внесем небольшие изменения в наш сайт, чуть-чуть кастомизировав его: изменим цвет подложки левой части сайта (где расположен список методов и ссылки на них).
Через инструменты разработчика модно увидеть, что левая часть сайта имеет CSS-класс
toc-wrapper, а цвет подложки для нее — #2E3336 (черный). Давайте заменим его, например, на цвет с HEX-кодом #5cd8df.Для этого в файле
slate_shards/basic/source/stylesheets/screen.css.scss найдите класс .toc-wrapper, Видно, что для него цвет подложки задан через переменную background-color: $nav-bg;. Можно изменить цвет, заменив значение $nav-bg на #5cd8df или же, заменив значение переменной $nav-bg в файле slate_shards/basic/source/stylesheets/_variables.scss. Если выбрать первый вариант, цвет изменится только для класса .toc-wrapper. Если же изменить значение переменной, тогда цвет изменится для всех классов и элементов, в CSS-правилах которых он используется.Я изменил значение переменной и цвет применился для подложки левой части сайта, а также для поля ввода формы поиска по сайту (т.к. он задается через ту же переменную
$nav-bg в файле slate_shards/basic/source/stylesheets/screen.css.scss).После внесения изменений не забудьте пересобрать сайт, чтобы увидеть результат.
Теперь вы знаете, как кастомизировать сайт-справочник, собранный с помощью
Foliant и Slate. Напоминаю, что только цветами возможности кастомизации не ограничиваются: при должной сноровке вы сможете придать сайту какой угодно вид и даже добавить интерактивности. Рекомендую потренироваться.В следующий раз разберемся, как документировать API с помощью
Foliant и Slate, если спецификации OpenAPI у вас (на проекте) нет, но есть возможность создавать описания методов вручную.👍8🤝2✍1
#apidocs
Привет.
Публикую очередной (и завершающий) урок курса по документированию API.
Сегодня рассмотрим процесс сборки справочника API, если на проекте нет спецификации в формате OpenAPI.
В таком случае техническому писателю придется:
1. Добыть информацию (у разработчиков, из кода, при самостоятельном тестировании уже разработанного API и пр.).
2. Сделать исходник в формате
3. Немного изменить конфигурацию в стартерпаке, который мы использовали на предыдущих уроках.
Процесс сбора информации рассматривать не будем, т.к. это отдельный вопрос. Разберемся только с пунктами 2 и 3 из списка выше.
Подготовка исходника для сборки справочника
Как было описано в предыдущем уроке (П.2 списка),
Я подготовил пример такого исходника с описанием одного метода (ссылка на него) и назвал его
Некоторые пояснения по нему:
- Первый заголовок первого уровня будет заголовком нашего сайта. Каждый последующий заголовок первого уровня будет восприниматься
- Заголовки второго уровня используются для обозначения методов API (в примере это
- Текст, который следует после
- При подготовке исходника можно использовать практически любые возможности Markdown, включая таблицы, inline HTML и пр.:
Полученный исходник нужно разместить в папке
Изменения в конфигурации в стартерпаке
Т.к. сборка сайта будет происходить из уже готового Markdown-источника, нужды в препроцессоре
В общем, это все, что нужно изменить, чтобы собрать сайт-справочник из Markdown-файла.
Можете подтянуть себе ветку
К слову, вы можете комбинировать сборку сайта из OpenAPI-спецификации и Markdown-файла одновременно. Как это сделать, описано в документации Foliant. Если интересно, можете попробовать самостоятельно.
На этом всё, курс закончен.
Позже я выложу все уроки на отдельном сайте, чтобы с курсом было удобнее работать.
Или не всё? Если захотите, в качестве бонусного урока можем рассмотреть, как «замокать» наш API с помощью Postman. Это будет полезным, например, для разработчиков и тестировщиков и поможет им на наглядном примере понять в первом приближении, как будет работать спроектированный API. Если есть такое желание, пишите в комментариях.
Привет.
Публикую очередной (и завершающий) урок курса по документированию API.
Сегодня рассмотрим процесс сборки справочника API, если на проекте нет спецификации в формате OpenAPI.
В таком случае техническому писателю придется:
1. Добыть информацию (у разработчиков, из кода, при самостоятельном тестировании уже разработанного API и пр.).
2. Сделать исходник в формате
.md для сборки справочника.3. Немного изменить конфигурацию в стартерпаке, который мы использовали на предыдущих уроках.
Процесс сбора информации рассматривать не будем, т.к. это отдельный вопрос. Разберемся только с пунктами 2 и 3 из списка выше.
Подготовка исходника для сборки справочника
Как было описано в предыдущем уроке (П.2 списка),
Slate собирает сайт-справочник из Markdown-исходника, который получается из OpenAPI-спецификации в результате ее обработки препроцессором swaggerdoc (с Widdershins под капотом). В случае, если OpenAPI-спецификации нет, подготовка этого самого Markdown-исходника ложится на плечи технического писателя.Я подготовил пример такого исходника с описанием одного метода (ссылка на него) и назвал его
api.md.Некоторые пояснения по нему:
- Первый заголовок первого уровня будет заголовком нашего сайта. Каждый последующий заголовок первого уровня будет восприниматься
Slate как заголовок, обозначающий группу методов API (в нашем случае это # techwriters).- Заголовки второго уровня используются для обозначения методов API (в примере это
## GET /techwriters).- Текст, который следует после
>, и блоки кода рендерятся в правой части сайта.- При подготовке исходника можно использовать практически любые возможности Markdown, включая таблицы, inline HTML и пр.:
Slate все благополучно переварит и сгенерирует сайт-справочник.Полученный исходник нужно разместить в папке
src. Изменения в конфигурации в стартерпаке
Т.к. сборка сайта будет происходить из уже готового Markdown-источника, нужды в препроцессоре
swaggerdoc у нас нет. Поэтому его можно отключить (я просто закомментировал его в foliant.yml для наглядности). Там же, в блоке chapters я изменил исходник, из которого будет собираться сайт.В общем, это все, что нужно изменить, чтобы собрать сайт-справочник из Markdown-файла.
Можете подтянуть себе ветку
reference_without_open_api_spec из репозитория, с которым мы работали на предыдущих уроках (или склонировать репозиторий полностью), если еще не делали этого ранее) и собрать сайт локально, как описано в этом уроке.К слову, вы можете комбинировать сборку сайта из OpenAPI-спецификации и Markdown-файла одновременно. Как это сделать, описано в документации Foliant. Если интересно, можете попробовать самостоятельно.
На этом всё, курс закончен.
Позже я выложу все уроки на отдельном сайте, чтобы с курсом было удобнее работать.
Или не всё? Если захотите, в качестве бонусного урока можем рассмотреть, как «замокать» наш API с помощью Postman. Это будет полезным, например, для разработчиков и тестировщиков и поможет им на наглядном примере понять в первом приближении, как будет работать спроектированный API. Если есть такое желание, пишите в комментариях.
🔥9👍3🤝1