Делаем статический сайт с материалами по курсу #apidocs?
Anonymous Poll
96%
Да.
2%
Нет.
2%
Какой еще курс?
PRO_техписательство
Приехал-таки мой диплом. Теперь официально: технический писатель системный аналитик.
В комментариях вы просили отдельный пост про обучение в «Нетологии»?
Держите отдельную статью.
Держите отдельную статью.
Хабр
Очередной обзор очередного курса. Или как техпис на системного аналитика в «Нетологии» учился
Привет, Хабр. Знаю, что здесь куча обзоров на различные курсы от разных школ, платформ и иже с ними. Но все-таки хочу вставить и свои 5 копеек. Рассказываю о своих ощущениях от курса «Системный...
🔥3👏3
#apidocs
Наступил вечер пятницы, а наш API обзавелся новыми методами для получения нужной информации.
Актуальные для данного этапа спецификации — на Gitlab и SwaggerHub.
Подробности и пояснения по некоторыми моментам — после выходных. И ответы на вопросы, если за выходные они у вас появятся.
Наступил вечер пятницы, а наш API обзавелся новыми методами для получения нужной информации.
Актуальные для данного этапа спецификации — на Gitlab и SwaggerHub.
Подробности и пояснения по некоторыми моментам — после выходных. И ответы на вопросы, если за выходные они у вас появятся.
👍3❤2🤝2🔥1
#apidocs
Привет.
Продолжаем курс по документированию API.
Первое
После прошлого поста у самых внимательных появились вопросы (спасибо, за то, что наблюдаете и поправляете).
В частности, при проектировании ресурса «Технический писатель» мы указали:
А при подготовке спецификации я вместо
Второе
На этапе проектирования мы предполагали, что будем оперировать двумя основными ресурсами: «Технический писатель» и «Навык». Но в процессе пришло понимание, что лучше будет ввести еще один (составной) ресурс «Навык технического писателя».
Почему так? Если оставить все как есть, то при добавлении каждого нового техписа для него нужно будет добавлять один или несколько навыков. Но ведь навыки у большинства техписов, как правило типовые (за исключением каких-то специфичных), например «Документирование API», «MkDocs», «Документирование кода» и т.д. Если для каждого техписа отдельно хранить полное описание набора навыков, у нас получится много дублей, что не есть хорошо.
Поэтому было принято решение:
1️⃣ Изменить ресурс «Навык». В частности, убираем из него поля «Подтверждающий документ» и «Ссылки на примеры».
Теперь у нас будут какие-то типовые навыки, общие для всех техписов. А для каждого конкретного специалиста они будут обогащаться данными.
2️⃣ Ввести составной ресурс «Навык технического писателя».
Он будет строиться из типового «Навыка» и дополняться полями, индивидуальными для каждого техписа. И выглядеть это может так:
Собственно, это сейчас и отражено в наших спецификациях.
Что дальше? Дальше добавим методы для добавления и изменения данных и перейдем к документированию API. Оставайтесь на связи.
Привет.
Продолжаем курс по документированию API.
Первое
После прошлого поста у самых внимательных появились вопросы (спасибо, за то, что наблюдаете и поправляете).
В частности, при проектировании ресурса «Технический писатель» мы указали:
|Название поля|Имя поля в API|Тип данных|
|-------------|--------------|----------|
|Имя |firstName |string |
А при подготовке спецификации я вместо
firstName написал name. Ошибку пофиксил, спасибо за замечание (тык, тык).Второе
На этапе проектирования мы предполагали, что будем оперировать двумя основными ресурсами: «Технический писатель» и «Навык». Но в процессе пришло понимание, что лучше будет ввести еще один (составной) ресурс «Навык технического писателя».
Почему так? Если оставить все как есть, то при добавлении каждого нового техписа для него нужно будет добавлять один или несколько навыков. Но ведь навыки у большинства техписов, как правило типовые (за исключением каких-то специфичных), например «Документирование API», «MkDocs», «Документирование кода» и т.д. Если для каждого техписа отдельно хранить полное описание набора навыков, у нас получится много дублей, что не есть хорошо.
Поэтому было принято решение:
1️⃣ Изменить ресурс «Навык». В частности, убираем из него поля «Подтверждающий документ» и «Ссылки на примеры».
|Название поля |Имя поля в API |Тип данных|
|---------------|----------------|----------|
|Идентификатор |id |integer |
|Название навыка|skillName |string |
|Описание навыка|skillDescription|string |
|Алиас |alias |string |
Теперь у нас будут какие-то типовые навыки, общие для всех техписов. А для каждого конкретного специалиста они будут обогащаться данными.
2️⃣ Ввести составной ресурс «Навык технического писателя».
Он будет строиться из типового «Навыка» и дополняться полями, индивидуальными для каждого техписа. И выглядеть это может так:
|Название поля |Имя поля в API. |Тип данных |
|-------------------------|------------------|--------------|
|Идентификатор техписателя|techwriterId |integer |
|Общая информация о навыке|skillCommonInfo |object (навык)|
|Подтверждающий документ |confirmingDocument|string |
|Ссылки на примеры |linksExamples |array(string) |
Собственно, это сейчас и отражено в наших спецификациях.
Что дальше? Дальше добавим методы для добавления и изменения данных и перейдем к документированию API. Оставайтесь на связи.
🤝2❤1👍1
Что-то давно стихов IT-шных у нас не было.
Придумалось вот за рулем:
На проде аффектится импорт.
На «тесте» регресс не прошел.
Я «фича» ребейзнул — конфликты.
QA новый баг вдруг нашел.
Тимлид мой МР не аппрувит.
Тех. дир вдруг позвал уан ту уан.
Стажер, блин, скиллы не импрувит.
На кой мне такой падаван?
Придумалось вот за рулем:
На проде аффектится импорт.
На «тесте» регресс не прошел.
Я «фича» ребейзнул — конфликты.
QA новый баг вдруг нашел.
Тимлид мой МР не аппрувит.
Тех. дир вдруг позвал уан ту уан.
Стажер, блин, скиллы не импрувит.
На кой мне такой падаван?
👍6🔥4😁3
#apidocs
Привет.
Суббота, все отдыхают, а наша спецификация API пополнилась новыми методами для добавления, изменения и удаления данных.
По сути, у нас все уже готово.
В начале курса мы условились, что в проектируемом API будут реализованы действия:
1️⃣ Получение списка технических писателей (метод GET /techwriters).
2️⃣ Получение списка скиллов (метод GET /skills).
3️⃣ Получение информации о техническом писателе по идентификатору (метод GET /techwriters/{techwriterId}).
4️⃣ Получение информации о навыке (метод GET /skills/{skillId}).
5️⃣ Добавление нового технического писателя (метод POST /techwriters/).
6️⃣ Редактирование сведений о техническом писателе (метод PATCH /techwriters/{techwriterId}).
7️⃣ Удаление технического писателя (метод DELETE /techwriters/{techwriterId}).
8️⃣ Добавление нового навыка (метод POST /skills).
9️⃣ Редактирование навыка (метод PATCH /skills/{skillId}).
🔟 Удаление навыка (метод DELETE /skills/{skillId}).
Итоговую спецификацию смотрите на SwaggerHub или в GitLab.
Пояснения и ответы на вопросы (если они будут) — на следующей неделе.
И еще. Делюсь полезным инструментом, который поможет вам визуализировать спецификацию в формате YAML, чтобы было удобнее смотреть «что откуда растет». Это — PlantUML. Нужно просто обернуть спецификацию в теги
и она отрисуется в виде картинки. Но есть нюанс: некоторые плагины PlantUML не понимают символ «|» в YAML (используется для многострочных блоков текста). Поэтому спецификацию нужно предварительно подготовить: убрать «|», блоки сделать в одну строку и убрать из них служебные символы (т.к. в этом случае уже будет «ругаться» YAML). Посмотреть, как это выглядит, можно, открыв в вашей IDE этот файл. Но у вас должно быть установлено расширение для работы с PlantUML (я использую VSCode и расширение PlantUML для него). Возможно, с вашим плагином (если будете использовать что-то другое) такого не случится, кто знает :).
Теперь, у нас уже есть одна из форм документации API — спецификация в формате OpenAPI.
Что дальше? А дальше мы будем генерить из нее статический сайт-справочник (не без docs as code, конечно же).
Будьте на связи.
Привет.
Суббота, все отдыхают, а наша спецификация API пополнилась новыми методами для добавления, изменения и удаления данных.
По сути, у нас все уже готово.
В начале курса мы условились, что в проектируемом API будут реализованы действия:
1️⃣ Получение списка технических писателей (метод GET /techwriters).
2️⃣ Получение списка скиллов (метод GET /skills).
3️⃣ Получение информации о техническом писателе по идентификатору (метод GET /techwriters/{techwriterId}).
4️⃣ Получение информации о навыке (метод GET /skills/{skillId}).
5️⃣ Добавление нового технического писателя (метод POST /techwriters/).
6️⃣ Редактирование сведений о техническом писателе (метод PATCH /techwriters/{techwriterId}).
7️⃣ Удаление технического писателя (метод DELETE /techwriters/{techwriterId}).
8️⃣ Добавление нового навыка (метод POST /skills).
9️⃣ Редактирование навыка (метод PATCH /skills/{skillId}).
🔟 Удаление навыка (метод DELETE /skills/{skillId}).
Итоговую спецификацию смотрите на SwaggerHub или в GitLab.
Пояснения и ответы на вопросы (если они будут) — на следующей неделе.
И еще. Делюсь полезным инструментом, который поможет вам визуализировать спецификацию в формате YAML, чтобы было удобнее смотреть «что откуда растет». Это — PlantUML. Нужно просто обернуть спецификацию в теги
@startyaml @endyaml
и она отрисуется в виде картинки. Но есть нюанс: некоторые плагины PlantUML не понимают символ «|» в YAML (используется для многострочных блоков текста). Поэтому спецификацию нужно предварительно подготовить: убрать «|», блоки сделать в одну строку и убрать из них служебные символы (т.к. в этом случае уже будет «ругаться» YAML). Посмотреть, как это выглядит, можно, открыв в вашей IDE этот файл. Но у вас должно быть установлено расширение для работы с PlantUML (я использую VSCode и расширение PlantUML для него). Возможно, с вашим плагином (если будете использовать что-то другое) такого не случится, кто знает :).
Теперь, у нас уже есть одна из форм документации API — спецификация в формате OpenAPI.
Что дальше? А дальше мы будем генерить из нее статический сайт-справочник (не без docs as code, конечно же).
Будьте на связи.
🔥8🤝4
#apidocs
Привет.
Продолжаем курс по документированию API.
В прошлый раз мы закончили разработку OpenAPI-спецификации и получили один из видов документации на API (есть что разработчикам показать).
Обещал дать некоторые пояснения по итоговой спецификации. Даю:
1️⃣ У кого-то может возникнуть вопрос, почему в Schemas гораздо больше схем, чем ресурсов, которые мы определили/спроектировали ранее. Так вот, здесь размещаются не только описания ресурсов, но и модели данных, которыми оперируют методы API: структуры запросов, ответов и т.д. — все, что отправляется и передается, переиспользуется и пр.
2️⃣ Почему для изменения ресурсов мы используем метод
Пожалуй, все. Если еще что-то не понятно, обращайтесь.
Что дальше? А дальше будем собирать статический справочник из нашей спецификации с помощью Foliant. Перед этим рекомендую вам форкнуть репозиторий с заготовкой, установить на своей компьютере Docker, прочесть Readme в указанном репозитории (там информации не очень много) и, по желанию, выполнить локальную сборку (а может даже и деплой), как там описано.
Привет.
Продолжаем курс по документированию API.
В прошлый раз мы закончили разработку OpenAPI-спецификации и получили один из видов документации на API (есть что разработчикам показать).
Обещал дать некоторые пояснения по итоговой спецификации. Даю:
1️⃣ У кого-то может возникнуть вопрос, почему в Schemas гораздо больше схем, чем ресурсов, которые мы определили/спроектировали ранее. Так вот, здесь размещаются не только описания ресурсов, но и модели данных, которыми оперируют методы API: структуры запросов, ответов и т.д. — все, что отправляется и передается, переиспользуется и пр.
2️⃣ Почему для изменения ресурсов мы используем метод
PATCH, если есть еще PUT? Действительно, изменять ресурс можно PATCH и PUT-методами. Но стандарты HTTP рекомендуют использовать PUT для полной замены или перемещения ресурса (подробнее). Т.е. если бы мы использовали PUT, то каждый раз при изменении данных, например, техписа или навыка, нужно было бы передавать полный набор полей. При использовании PATCH же можно передать только те поля, которые нужно перезаписать.Пожалуй, все. Если еще что-то не понятно, обращайтесь.
Что дальше? А дальше будем собирать статический справочник из нашей спецификации с помощью Foliant. Перед этим рекомендую вам форкнуть репозиторий с заготовкой, установить на своей компьютере Docker, прочесть Readme в указанном репозитории (там информации не очень много) и, по желанию, выполнить локальную сборку (а может даже и деплой), как там описано.
GitLab
denmaloyreb / foliant_slate_starterpack · GitLab
🔥7❤1
#apidocs
Привет. Продолжаем наш курс.
Сегодня сделаем магию — соберем статический сайт-справочник API из ранее созданной спецификации.
Чтобы магия свершилась, у вас на компьютере должны быть:
1️⃣ Git, чтобы работать с репозиторием со стартерпаком для сборки справочника API.
2️⃣ Docker, чтобы можно было собрать сайт-справочник и посмотреть его локально.
Если (когда) Git и Docker установлены:
1️⃣ Форкните себе репозиторий со стартерпаком для сборки справочника API с Foliant. Для этого у вас должен быть аккаунт на GitLab (процесс создания аккаунта и форка репозитория опустим — с этим предлагаю разобраться самостоятельно).
Когда будете форкать репозиторий, GitLab предложит придумать для него имя (можно оставить как есть). Я свой форк назвал
2️⃣ Склонируйте форкнутый репозиторий себе на локальный компьютер.
3️⃣ Откройте репозиторий в любом IDE. И сделайте следующие изменения:
✅ добавьте в корень репозитория файл с расширением .yaml. Имя ему можно дать любое. Я назвал этот файл
✅ скопируйте в созданный на предыдущем шаге файл содержимое итоговой спецификации API (ссылка на нее). Не забудьте сохранить изменения.
✅ найдите в корне репозитория файл
4️⃣ Соберите сайт. Для этого запустите терминал (консоль) в папке склонированного репозитория и выполните команду:
Готово. В случае успешного выполнения команды вы увидите в терминале (консоли) сообщение вроде:
а в папке склонированного репозитория появится папка
Теперь, чтобы посмотреть результат сборки, можете перейти в папку
Поздравляю. Вы собрали сайт с дефолтными настройками.
Что дальше? В следующих постах я постараюсь рассказать, что здесь вообще происходит при сборке, а также рассмотрим некоторые моменты, связанные с кастомизацией сайта.
БОНУС. При желании можете сразу же опубликовать свой сайт на GitLab pages (в репозитории со стартерпаком есть все настройки для этого). Для этого сделайте коммит с изменениями и запушьте изменения в ветку main (конечно, пушить сразу в main не есть хорошо, но мы же работаем с репозиторием сами и учимся).
Если все хорошо, в разделе
FYI. Те, у кого получилось задеплоить свой сайт на GitLab pages, оставляйте ссылки в комментариях.
Привет. Продолжаем наш курс.
Сегодня сделаем магию — соберем статический сайт-справочник API из ранее созданной спецификации.
Чтобы магия свершилась, у вас на компьютере должны быть:
1️⃣ Git, чтобы работать с репозиторием со стартерпаком для сборки справочника API.
2️⃣ Docker, чтобы можно было собрать сайт-справочник и посмотреть его локально.
Если (когда) Git и Docker установлены:
1️⃣ Форкните себе репозиторий со стартерпаком для сборки справочника API с Foliant. Для этого у вас должен быть аккаунт на GitLab (процесс создания аккаунта и форка репозитория опустим — с этим предлагаю разобраться самостоятельно).
Когда будете форкать репозиторий, GitLab предложит придумать для него имя (можно оставить как есть). Я свой форк назвал
api_docs_foliant_slate_starterpack.2️⃣ Склонируйте форкнутый репозиторий себе на локальный компьютер.
3️⃣ Откройте репозиторий в любом IDE. И сделайте следующие изменения:
✅ добавьте в корень репозитория файл с расширением .yaml. Имя ему можно дать любое. Я назвал этот файл
techwriters.yaml.✅ скопируйте в созданный на предыдущем шаге файл содержимое итоговой спецификации API (ссылка на нее). Не забудьте сохранить изменения.
✅ найдите в корне репозитория файл
foliant.yml. В нем, в строке 8, замените pet_swagger.json на имя файла, который был добавлен в папку на предудщих шагах (в моем случае это techwriters.yaml). Не забудьте сохранить изменения.4️⃣ Соберите сайт. Для этого запустите терминал (консоль) в папке склонированного репозитория и выполните команду:
docker-compose run --rm foliant make site --with slateГотово. В случае успешного выполнения команды вы увидите в терминале (консоли) сообщение вроде:
...
Project built successfully.
Done
────────────────────
Result: API.slate/
а в папке склонированного репозитория появится папка
API.slate — это и есть наш статический сайт справочник.Теперь, чтобы посмотреть результат сборки, можете перейти в папку
API.slate и открыть файл index.html.Поздравляю. Вы собрали сайт с дефолтными настройками.
Что дальше? В следующих постах я постараюсь рассказать, что здесь вообще происходит при сборке, а также рассмотрим некоторые моменты, связанные с кастомизацией сайта.
БОНУС. При желании можете сразу же опубликовать свой сайт на GitLab pages (в репозитории со стартерпаком есть все настройки для этого). Для этого сделайте коммит с изменениями и запушьте изменения в ветку main (конечно, пушить сразу в main не есть хорошо, но мы же работаем с репозиторием сами и учимся).
Если все хорошо, в разделе
Build -> Pipelines вашего репозитория на GitLab появится успешный пайплан (подсвечивается зеленым цветом). А в разделе Deploy -> Pages — ссылка на собранный сайт (см. скрины в комментариях к посту). Мой сайт, например, опубликовался по ссылке.FYI. Те, у кого получилось задеплоить свой сайт на GitLab pages, оставляйте ссылки в комментариях.
🔥6🤝3❤1
Сегодня пост не по теме курса.
Попалась классная статья про GraphQL — прямо то, что нужно для старта и погружения.
Ох, если бы она была тогда, когда мне пришлось вникать в GraphQL.
В общем, категорически рекомендую.
Попалась классная статья про GraphQL — прямо то, что нужно для старта и погружения.
Ох, если бы она была тогда, когда мне пришлось вникать в GraphQL.
В общем, категорически рекомендую.
Хабр
GraphQL — знакомство на практике через Postman [пошаговая инструкция]
Для интеграции и разработки систем в основном используется REST API, но, помимо него, есть и другие программные интерфейсы, как GraphQL. Они менее популярны, но не менее актуальны. В этой статье я...
2✍7👍3
Я только сегодня осознал, что Айтишечка преследовала меня всегда и пыталась засосать в себя. И засосала-таки
На пятом курсе военной академии я выбрал тему диплома «Разработка интерактивного тренажера для обучения личного состава работе с аппаратной … (дальше секретно)». Это была программа (если ее так можно назвать вообще), разработанная с помощью Macromedia Flash 8 и Acrion Script 2.0. Получилось норм. Даже акт внедрения в учебный процесс получил.
Потом Айтишечка напомнила о себе снова, когда пришло время курсовой и дипломной работ жены. Ей я сделал 2 программы (все с помощью тех же Macromedia Flash 8 и Acrion Script 2.0) для работы с детьми (она на дефектолога училась). Программы, кстати тоже активно используют в универе до сих пор.
Затем кривая жизни завела меня в копирайтиг. Но и тут без Айтишечки не обошлось. Со временем я переквалифицировался исключительно на тексты по IT-тематике.
Дальше-больше (или с кем поведешься, от того и наберешься). Я получил вторую вышку с дипломом, в котором написано «Инженер-программист». Тема дипломной работы была «Разработка CRM-системы для учета проектов фрилансера-копирайтера/редактора». Сделал все на PHP+HTML+JavaScript и подружил это дело с базой. По сути, это был одностраничник с табличками, в который подгружались данные о проектах из базы и можно было создавать новые, менять существующие проекты, вести учет финансов и т.д. В отдельном фрейме можно было загрузить и полезные для копирайтера сервисы: glvrd, Advego, Text.ru и etxt.
После универа продолжал работать копирайтером почти 2 года. А потом… Бац — и я работаю техписом в IT. И теперь я понимаю, что это надолго. Ведь это то, чего я хотел: некий симбиоз писателя, программиста и еще каких-то там айтишных специальностей.
Все-таки Айтишечка добилась своего — она меня засосала. И это чертовски приятно осознавать.
На пятом курсе военной академии я выбрал тему диплома «Разработка интерактивного тренажера для обучения личного состава работе с аппаратной … (дальше секретно)». Это была программа (если ее так можно назвать вообще), разработанная с помощью Macromedia Flash 8 и Acrion Script 2.0. Получилось норм. Даже акт внедрения в учебный процесс получил.
Потом Айтишечка напомнила о себе снова, когда пришло время курсовой и дипломной работ жены. Ей я сделал 2 программы (все с помощью тех же Macromedia Flash 8 и Acrion Script 2.0) для работы с детьми (она на дефектолога училась). Программы, кстати тоже активно используют в универе до сих пор.
Затем кривая жизни завела меня в копирайтиг. Но и тут без Айтишечки не обошлось. Со временем я переквалифицировался исключительно на тексты по IT-тематике.
Дальше-больше (или с кем поведешься, от того и наберешься). Я получил вторую вышку с дипломом, в котором написано «Инженер-программист». Тема дипломной работы была «Разработка CRM-системы для учета проектов фрилансера-копирайтера/редактора». Сделал все на PHP+HTML+JavaScript и подружил это дело с базой. По сути, это был одностраничник с табличками, в который подгружались данные о проектах из базы и можно было создавать новые, менять существующие проекты, вести учет финансов и т.д. В отдельном фрейме можно было загрузить и полезные для копирайтера сервисы: glvrd, Advego, Text.ru и etxt.
После универа продолжал работать копирайтером почти 2 года. А потом… Бац — и я работаю техписом в IT. И теперь я понимаю, что это надолго. Ведь это то, чего я хотел: некий симбиоз писателя, программиста и еще каких-то там айтишных специальностей.
Все-таки Айтишечка добилась своего — она меня засосала. И это чертовски приятно осознавать.
🔥16👍10👾3
#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
Итоги года (а как же без них? ):
- Попробовал себя в роли спикера. Выступил на TW Days 1 и мне понравилось (надеюсь, что слушателям тоже). Готовлю доклад для TW Days 2.
- Довольно много путешествовал с семьей на авто (за год около 35 000 км пробега получилось).
- Получил диплом системного аналитика. И даже поработал несколько месяцев СА.
- Сменил работу (получилось как-то внезапно, спонтанно, внепланово). Пока нравится.
- Купип сапборд. Доволен как слон. Правда, во время последнего в сезоне заплыва утопил очки👓.
- Получил 336 новых подписчиков на канал. Пожалуй, это один из главных и значимых для меня итогов: значит, кому-то интересна моя писанина. Спасибо за то, что читаете канал. В следующем году постараюсь радовать подписчиков новыми интересными и полезными постами (почаще ).
С наступающим 2025 годом!!! Всем желаю «сбычи мечт», чтобы список итогов в 2025 году был длинным и состоял только из приятных пунктов.
- Попробовал себя в роли спикера. Выступил на TW Days 1 и мне понравилось (надеюсь, что слушателям тоже). Готовлю доклад для TW Days 2.
- Довольно много путешествовал с семьей на авто (за год около 35 000 км пробега получилось).
- Получил диплом системного аналитика. И даже поработал несколько месяцев СА.
- Сменил работу (получилось как-то внезапно, спонтанно, внепланово). Пока нравится.
- Купип сапборд. Доволен как слон. Правда, во время последнего в сезоне заплыва утопил очки👓.
- Получил 336 новых подписчиков на канал. Пожалуй, это один из главных и значимых для меня итогов: значит, кому-то интересна моя писанина. Спасибо за то, что читаете канал. В следующем году постараюсь радовать подписчиков новыми интересными и полезными постами (
С наступающим 2025 годом!!! Всем желаю «сбычи мечт», чтобы список итогов в 2025 году был длинным и состоял только из приятных пунктов.
❤22🔥8
Осталось всего 2 месяца до TechWriter Days #2. Программа уже сформирована. Интересных докладов будет много. Потихоньку формирую для себя список тех, на которые пойду.
🔥3
Forwarded from Эльдар Султанов
Программа конференции TechWriter Days #2 сформирована! 🎉
Вас ждут 60+ докладов и мастер-классов, 2 дня профессионального общения с 400+ участниками из сотен компаний СНГ, полезные инсайты и новые знания!
Станьте частью этого важного события, которое состоится 28-29 марта в Санкт-Петербурге по адресу ул. Стартовая 6, лит. А, отель Airportcity Plaza🙏🏼
⚡️билеты
⚡️афиша
⚡️скидки
⚡️видео
Ждем вас на TechWriter Days #2! 🚀
Вас ждут 60+ докладов и мастер-классов, 2 дня профессионального общения с 400+ участниками из сотен компаний СНГ, полезные инсайты и новые знания!
Станьте частью этого важного события, которое состоится 28-29 марта в Санкт-Петербурге по адресу ул. Стартовая 6, лит. А, отель Airportcity Plaza🙏🏼
⚡️билеты
⚡️афиша
⚡️скидки
⚡️видео
Ждем вас на TechWriter Days #2! 🚀
🔥5👍1
Эльдар Султанов
Программа конференции TechWriter Days #2 сформирована! 🎉 Вас ждут 60+ докладов и мастер-классов, 2 дня профессионального общения с 400+ участниками из сотен компаний СНГ, полезные инсайты и новые знания! Станьте частью этого важного события, которое состоится…
Если нашли меня на фото из анонса конференции, ставьте ❤️
❤11
Forwarded from Техпис говорит | Подкасты (Anna Kostyagina)
С Днем технического писателя, друзья и коллеги!
Ведь сегодня 2 февраля - 33-й день года ✨️
#праздник #деньтехписателя
Ведь сегодня 2 февраля - 33-й день года ✨️
#праздник #деньтехписателя
🥰12
Говорят, сегодня день технического писателя. Ну что же, ловите несколько строк, посвященных нам с вами:
Одни по ГОСТу пишут доку.
Другие пишут доку на «АПИшки».
Одни всё собирают «Диплодоком».
Другие «Вордом» мучают нервишки.
Одни читают код и парсеры ваяют.
Другие из стейкхолдеров достанут что угодно.
Одни в большущих «Госах» обитают.
Другим в стартапах просто превосходно.
Одни лишь пишут только руководства.
Другие за докопсов поработать бы не против.
Одни в IT, другие — на каком-то производстве.
Кто-то из них болтун, другой не разговорчив.
Все это про техписов, без которых
Хороших доков быть не может просто.
Про новичков совсем и про матёрых.
Про «докс эс кодников» и про адептов ГОСТа.
Сегодня их поздравить не забудьте.
Ведь это же совсем несложно.
Техписы, вы всегда такими будьте.
Такими, без которых невозможно!
Одни по ГОСТу пишут доку.
Другие пишут доку на «АПИшки».
Одни всё собирают «Диплодоком».
Другие «Вордом» мучают нервишки.
Одни читают код и парсеры ваяют.
Другие из стейкхолдеров достанут что угодно.
Одни в большущих «Госах» обитают.
Другим в стартапах просто превосходно.
Одни лишь пишут только руководства.
Другие за докопсов поработать бы не против.
Одни в IT, другие — на каком-то производстве.
Кто-то из них болтун, другой не разговорчив.
Все это про техписов, без которых
Хороших доков быть не может просто.
Про новичков совсем и про матёрых.
Про «докс эс кодников» и про адептов ГОСТа.
Сегодня их поздравить не забудьте.
Ведь это же совсем несложно.
Техписы, вы всегда такими будьте.
Такими, без которых невозможно!
1❤22🔥12👏3👎1