Ура!!! Я только что защитил дипломный проект!!!
8 месяцев обучения пролетели незаметно. И было это продуктивно.
Теперь я не только технический писатель, но иподробности позже .
8 месяцев обучения пролетели незаметно. И было это продуктивно.
Теперь я не только технический писатель, но и
🔥12🏆9👍2👏1
Техпис не должен... Или рынок все порешает
Наверное, это холиварная тем, но все-таки.
Что-то в последнее время все чаще стали попадаться высказывания типа «Техпис не должен...». Как правило, они всплывают в обсуждениях вакансий.
У большего количества таких высказываний посыл такой: мол техпис не должен делать ничего, кроме как писать инструкции.
Они говорят, что техпис не должен:
- описывать архитектуру,
- участвовать в написании спецификаций,
- лезть в код и разбираться с тем, чего там понаписали разработчики,
- настраивать пайплайны сборки документации,
- рисовать диаграммы за аналитиков и архитекторов....
А вот я так не считаю. Я думаю, что техпис должен. Должен стремиться к тому, чтобы пощупать всё, попробовать всё, понабивать шишки обо всё.
Должен, но с оговоркой: если работодатель достойно за это платит (достойная оплата — это тема для отдельного разговора).
Почему техпис должен? Я считаю, что это полезно для него же в первую очередь. Я уверен, что востребованный на рынке технический писатель — это T-shape специалист. А как стать таким специалистом, если ты свято веришь в «Техпис не должен»?
Водитель фуры, например тоже не должен менять колесо (для этого есть специальные бригады). Но большинство дальнобойщиков не ждет, пока к ним приедет эта самая бригада. Они берут и делают все самостоятельно.
Разработчики, по-хорошему, не должны настраивать CI/CD для своих продуктов (есть же девопсы под это дело). Но знаю, что многие сами это делают.
Да, может быть, в идеальном мире технический писатель реально не должен ничего, кроме как сидеть в уголочке и тихонько писать свои инструкции. Но живем мы в мире реальном. И я считаю, что техпис еще много чего должен (при условии получения соответствующего поощрения от работодателя). А за тех, кто «не должен» рынок все сам порешает.
Что скажете?
Наверное, это холиварная тем, но все-таки.
Что-то в последнее время все чаще стали попадаться высказывания типа «Техпис не должен...». Как правило, они всплывают в обсуждениях вакансий.
У большего количества таких высказываний посыл такой: мол техпис не должен делать ничего, кроме как писать инструкции.
Они говорят, что техпис не должен:
- описывать архитектуру,
- участвовать в написании спецификаций,
- лезть в код и разбираться с тем, чего там понаписали разработчики,
- настраивать пайплайны сборки документации,
- рисовать диаграммы за аналитиков и архитекторов....
А вот я так не считаю. Я думаю, что техпис должен. Должен стремиться к тому, чтобы пощупать всё, попробовать всё, понабивать шишки обо всё.
Должен, но с оговоркой: если работодатель достойно за это платит (достойная оплата — это тема для отдельного разговора).
Почему техпис должен? Я считаю, что это полезно для него же в первую очередь. Я уверен, что востребованный на рынке технический писатель — это T-shape специалист. А как стать таким специалистом, если ты свято веришь в «Техпис не должен»?
Водитель фуры, например тоже не должен менять колесо (для этого есть специальные бригады). Но большинство дальнобойщиков не ждет, пока к ним приедет эта самая бригада. Они берут и делают все самостоятельно.
Разработчики, по-хорошему, не должны настраивать CI/CD для своих продуктов (есть же девопсы под это дело). Но знаю, что многие сами это делают.
Да, может быть, в идеальном мире технический писатель реально не должен ничего, кроме как сидеть в уголочке и тихонько писать свои инструкции. Но живем мы в мире реальном. И я считаю, что техпис еще много чего должен (при условии получения соответствующего поощрения от работодателя). А за тех, кто «не должен» рынок все сам порешает.
Что скажете?
💯16❤3🌚1
Техписа на них нет...
Увидел в лифте такие вот правила пользования.
И они мне сломали мозг. Попросил жену и детей посмотреть на это и сказать, что здесь не так.
И все трое, включая 10-летнего ребенка, указали на одну и ту же проблему (которую я тоже сразу увидел).
Как думаете, что смутило всех в этой картинке?
Увидел в лифте такие вот правила пользования.
И они мне сломали мозг. Попросил жену и детей посмотреть на это и сказать, что здесь не так.
И все трое, включая 10-летнего ребенка, указали на одну и ту же проблему (которую я тоже сразу увидел).
Как думаете, что смутило всех в этой картинке?
🤯3😱1
Долго не можете найти техписа? Возможно, вам нужно поменять рекрутера
За последний месяц я получил 16 предложений от разных компаний (работу, если что, пока не ищу, они просто сами на меня выходят).
Заметил одну вещь. Ну как заметил, я и ранее, когда занимался контентом для агентства IT-рекрутинга, об этом знал. Но думал, что сейчас все стало лучше.
А вот хрен. Ничего лучше не стало, и многие HRы и рекрутеры не хотят работать.
Почти каждому из написавших мне я задавал уточняющие вопросы по вакансии. Из 16 вакансий вопросов не возникло по 6 (там все было понятно и доходчиво расписано).
По десяти полученным предложениям были отправлены уточняющие вопросы (про вилку, стек, условия удалёнки и пр.). И только по трем была получена обратная связь. Остальные 7 HRов (или рекрутеров) просто молча отвалились. Естественно, когда они придут в следующий раз с предложениями, так же столкнутся с молчанием :) Я неверю, что они могут искать ответы на вопросы по 1-2 неделе, если что.
Вот вам и причина долгих поисков. Она на поверхности: кто-то на букву «Эйчар» или «Рекр» просто не хочет нормально работать.
Недавно в одном из каналов для бизнесменов рассматривался похожий кейс. Компания более полугода не могла найти сварщика. Когда начали разбираться, куда ж делись все сварщики, проанализировали критерии, по которым HR вела поиски (и чуть не поседели). Среди критериев там был возраст до 30 лет, амбициозность и … барабанная дробь … активность в Инсте (активность в Инсте сварщика, блеать!!!). За поиски взялся руководитель и нашел спеца за 3 дня.
Техписы, конечно, не сварщики, но подход к их поиску, как я погляжу, у некоторых примерно такой же — спустя рукава.
Удачи в поисках. И если они затянулись, бегите к HRу (рекрутеру) и смотрите, что и как он это делает.
За последний месяц я получил 16 предложений от разных компаний (работу, если что, пока не ищу, они просто сами на меня выходят).
Заметил одну вещь. Ну как заметил, я и ранее, когда занимался контентом для агентства IT-рекрутинга, об этом знал. Но думал, что сейчас все стало лучше.
А вот хрен. Ничего лучше не стало, и многие HRы и рекрутеры не хотят работать.
Почти каждому из написавших мне я задавал уточняющие вопросы по вакансии. Из 16 вакансий вопросов не возникло по 6 (там все было понятно и доходчиво расписано).
По десяти полученным предложениям были отправлены уточняющие вопросы (про вилку, стек, условия удалёнки и пр.). И только по трем была получена обратная связь. Остальные 7 HRов (или рекрутеров) просто молча отвалились. Естественно, когда они придут в следующий раз с предложениями, так же столкнутся с молчанием :) Я неверю, что они могут искать ответы на вопросы по 1-2 неделе, если что.
Вот вам и причина долгих поисков. Она на поверхности: кто-то на букву «Эйчар» или «Рекр» просто не хочет нормально работать.
Недавно в одном из каналов для бизнесменов рассматривался похожий кейс. Компания более полугода не могла найти сварщика. Когда начали разбираться, куда ж делись все сварщики, проанализировали критерии, по которым HR вела поиски (и чуть не поседели). Среди критериев там был возраст до 30 лет, амбициозность и … барабанная дробь … активность в Инсте (активность в Инсте сварщика, блеать!!!). За поиски взялся руководитель и нашел спеца за 3 дня.
Техписы, конечно, не сварщики, но подход к их поиску, как я погляжу, у некоторых примерно такой же — спустя рукава.
Удачи в поисках. И если они затянулись, бегите к HRу (рекрутеру) и смотрите, что и как он это делает.
💯11👍1
Идентификатор ресурса в API. Когда его можно назвать хорошим
Идентификаторы (далее ID) позволяют однозначно идентифицировать (простите за тавтологию) конкретный объект (или ресурс API в нашем случае). И к их формированию не стоит подходить «спустя рукава»: хотя казалось бы, что там придумывать, просто взял и пронумеровал все (нот нет, не прокатит).
В разных источниках встречается от 5 до 8 атрибутов (или признаков), за счет которых ID можно назвать хорошим. Больше всего мне понравилось, как это сформулировал Д. Гивакс.
Он выделяет следующие атрибуты хороших идентификаторов ресурсов API:
1️⃣ Уникальность.
2️⃣ Непредсказуемость.
3️⃣ Простота использования.
4️⃣ Постоянство.
5️⃣ Быстрота и легкость генерации.
6️⃣ Читабельность.
7️⃣ Информационная плотность.
Подробно эти атрибуты (если не все, то большую часть ) разберем в следующих постах. И тогда вы поймете, почему использовать в качестве ID просто цифры по порядку с единицы (или нуля) и далее — не есть хорошо, или почему в идентификаторах не рекомендуют использовать некоторые буквы, цифры и символы.
Идентификаторы (далее ID) позволяют однозначно идентифицировать (простите за тавтологию) конкретный объект (или ресурс API в нашем случае). И к их формированию не стоит подходить «спустя рукава»: хотя казалось бы, что там придумывать, просто взял и пронумеровал все (нот нет, не прокатит).
В разных источниках встречается от 5 до 8 атрибутов (или признаков), за счет которых ID можно назвать хорошим. Больше всего мне понравилось, как это сформулировал Д. Гивакс.
Он выделяет следующие атрибуты хороших идентификаторов ресурсов API:
1️⃣ Уникальность.
2️⃣ Непредсказуемость.
3️⃣ Простота использования.
4️⃣ Постоянство.
5️⃣ Быстрота и легкость генерации.
6️⃣ Читабельность.
7️⃣ Информационная плотность.
Подробно эти атрибуты (
✍4👍1
Вопрос для утра пятницы.
Метод GET в HTTP API:
Метод GET в HTTP API:
Anonymous Poll
57%
Всегда идемпотентен. Зуб даю.
43%
Ну нет же, не всегда.
❤2🔥1💩1🤡1
Кто хочет вкатиться в Docs as code? У моего коллеги в канале стартовал курс (бесплатный!!!!) для новичков.
Присоединяйтесь, Антон плохому не научит.
Присоединяйтесь, Антон плохому не научит.
🔥7
Forwarded from Parawriter
Привет!
Ну вот, закончились посты про погружение в профессию, и стало немного грустно. Может, организуем какую-нибудь новую серию тематических публикаций?
Что скажете, если мы проведём практический курс по docs-as-code? Будет весело — познакомимся с подходом «Документация как код» (в моей интерпретации), настроим инструменты и организуем настоящий процесс работы с документацией через git с последующей публикацией на сгенерированном html-сайте. Всё по-настоящему, но без трудностей и нюансов, которые встречаются на пути техписателя в реальной рабочей жизни.
Назовём этот курс как-нибудь романтично —маэстро! Docs as code для самых маленьких.
Работаем по проверенной схеме — посты курса будут публиковаться с хештегом #docsascode в хронологическом порядке и с относительно стабильной периодичностью 🙃
Право перебивать тематические публикации чем-то ещё оставляю за собой:)
Надеюсь, мы все хорошо проведём время!
P.S. Курс бесплатный, но ваши сердечки, птички, рукопожатия и даже звёздочки будут лучшей наградой!
#практика
Ну вот, закончились посты про погружение в профессию, и стало немного грустно. Может, организуем какую-нибудь новую серию тематических публикаций?
Что скажете, если мы проведём практический курс по docs-as-code? Будет весело — познакомимся с подходом «Документация как код» (в моей интерпретации), настроим инструменты и организуем настоящий процесс работы с документацией через git с последующей публикацией на сгенерированном html-сайте. Всё по-настоящему, но без трудностей и нюансов, которые встречаются на пути техписателя в реальной рабочей жизни.
Назовём этот курс как-нибудь романтично —
Работаем по проверенной схеме — посты курса будут публиковаться с хештегом #docsascode в хронологическом порядке и с относительно стабильной периодичностью 🙃
Право перебивать тематические публикации чем-то ещё оставляю за собой:)
Надеюсь, мы все хорошо проведём время!
P.S. Курс бесплатный, но ваши сердечки, птички, рукопожатия и даже звёздочки будут лучшей наградой!
#практика
🔥17
А не хотите мини-курс по документированию API?
Хочу сделать мини-курс по документированию HTTP API.
Но не совсем прям только по документированию.
Я вижу это все так:
1. Мы спроектируем свой API. Небольшой такой, буквально на несколько методов. Это позволит вам немного побыть в роли того, кто этим занимается, и в общих чертах понять, как это все происходит.
2. Далее мы создадим для этого API спецификацию в формате Open API. И это уже будет одним из видов документации.
3. Затем из полученной спецификации мы сгенерируем статический сайт-справочник. Для этого будем использовать Foliant. Возможно, попробуем и другие инструменты, чтобы почувствовать разницу.
4. Напишем доку вручную (как будто у нас нет Open API-спецификации) и снова генерируем сайт-справочник из всего этого.
И не хотелось бы, чтобы на этом все закончилось. Я думаю (не обещаю, но хотелось бы это реализовать), что мы замокаем API, либо развернем его с помощью специального сервиса, или же вообще сгенерируем код бэкенда и разместим все это дело где-нибудь. Потом «подергаем API-ручки», чтобы вы знали, с какой стороны подойти к API.
Как вам идея? Если этот пост наберет 30 сердечек ❤️ к исходу среды (18 сентября), мини-курсу быть, не наберет — ну и фиг с ним, с этим курсом.
Все будет происходить здесь, в этом канале.
Предложения и пожелания приветствуются: оставляйте их в комментах. И если знаете кого-то, кому это может быть интересно, приглашайте в канал.
Хочу сделать мини-курс по документированию HTTP API.
Но не совсем прям только по документированию.
Я вижу это все так:
1. Мы спроектируем свой API. Небольшой такой, буквально на несколько методов. Это позволит вам немного побыть в роли того, кто этим занимается, и в общих чертах понять, как это все происходит.
2. Далее мы создадим для этого API спецификацию в формате Open API. И это уже будет одним из видов документации.
3. Затем из полученной спецификации мы сгенерируем статический сайт-справочник. Для этого будем использовать Foliant. Возможно, попробуем и другие инструменты, чтобы почувствовать разницу.
4. Напишем доку вручную (как будто у нас нет Open API-спецификации) и снова генерируем сайт-справочник из всего этого.
И не хотелось бы, чтобы на этом все закончилось. Я думаю (не обещаю, но хотелось бы это реализовать), что мы замокаем API, либо развернем его с помощью специального сервиса, или же вообще сгенерируем код бэкенда и разместим все это дело где-нибудь. Потом «подергаем API-ручки», чтобы вы знали, с какой стороны подойти к API.
Как вам идея? Если этот пост наберет 30 сердечек ❤️ к исходу среды (18 сентября), мини-курсу быть, не наберет — ну и фиг с ним, с этим курсом.
Все будет происходить здесь, в этом канале.
Предложения и пожелания приветствуются: оставляйте их в комментах. И если знаете кого-то, кому это может быть интересно, приглашайте в канал.
1❤47🔥8
PRO_техписательство
А не хотите мини-курс по документированию API? Хочу сделать мини-курс по документированию HTTP API. Но не совсем прям только по документированию. Я вижу это все так: 1. Мы спроектируем свой API. Небольшой такой, буквально на несколько методов. Это позволит…
Дожидаться исхода среды не пришлось.
На утро есть 35 сердечек.
Значит, курсу быть.
В понедельник (23.09) опубликую подробности и правила.
Не теряйтесь.
На утро есть 35 сердечек.
Значит, курсу быть.
В понедельник (23.09) опубликую подробности и правила.
Не теряйтесь.
🔥10❤5
PRO_техписательство
Ура!!! Я только что защитил дипломный проект!!! 8 месяцев обучения пролетели незаметно. И было это продуктивно. Теперь я не только технический писатель, но и подробности позже .
Приехал-таки мой диплом.
Теперь официально: технический писатель системный аналитик.
Теперь официально: технический писатель системный аналитик.
🔥28
Привет, сегодня понедельник, 23.09, а значит, пора начинать наш мини-курс по проектированию API.
Итак, тренироваться будем накошках техписах.
В рамках курса мы спроектируем и задокументируем API (REST like, не побоюсь этого слова) в соответствии с ТЗ:
Цель: Разработать API для управления базой данных о технических писателях и их навыках.
Сущности, которыми будет оперировать API:
Технический писатель. Поля: ID, имя, отчество, фамилия, опыт работы, список навыков (скилл), контактные данные.
Навык: ID, название навыка, алиас, описание навыка, подтверждающий документ, ссылки на примеры.
Действия, которые будут реализованы в API:
- Получение списка технических писателей.
- Получение списка скиллов.
- Получение информации о техническом писателе по идентификатору.
- Получение информации о навыке.
- Добавление нового технического писателя.
- Редактирование сведений о техническом писателе.
- Удаление технического писателя.
- Добавление нового навыка.
- Редактирование навыка.
- Удаление навыка.
А теперь правила, ограничения, условия:
1. Не будем запихивать в сущности кучу полей. Наша цель все-таки — научиться документировать.
2. Не будем пытаться соблюсти все паттерны проектирования API и следовать best practices. Наша цель — см. П1.
3. Не будем описывать схему и принципы авторизации. Про цель вы в курсе :), да?
4. Не будем останавливаться на каких-то базовых вещах типа установки git на компьютер, настройки рабочего окружения и, глубокой теории по технологиям и инструментам. Но если будут возникать вопросы, будем стараться решать их вместе.
Про периодичность публикации постов. Не буду публиковать их часто: не более двух постов из курса в неделю, чтобы все смогли в нормальном темпе переваривать информацию и разбираться с возникающими вопросами.
Посты из курса буду помечать хэштегом #apidocs.
Вопросы, жалобы, предложения?
Следующий пост будет в четверг, 26.09: займемся описанием и проектированием сущностей API.
До встречи.
Итак, тренироваться будем на
В рамках курса мы спроектируем и задокументируем API (REST like, не побоюсь этого слова) в соответствии с ТЗ:
Цель: Разработать API для управления базой данных о технических писателях и их навыках.
Сущности, которыми будет оперировать API:
Технический писатель. Поля: ID, имя, отчество, фамилия, опыт работы, список навыков (скилл), контактные данные.
Навык: ID, название навыка, алиас, описание навыка, подтверждающий документ, ссылки на примеры.
Действия, которые будут реализованы в API:
- Получение списка технических писателей.
- Получение списка скиллов.
- Получение информации о техническом писателе по идентификатору.
- Получение информации о навыке.
- Добавление нового технического писателя.
- Редактирование сведений о техническом писателе.
- Удаление технического писателя.
- Добавление нового навыка.
- Редактирование навыка.
- Удаление навыка.
А теперь правила, ограничения, условия:
1. Не будем запихивать в сущности кучу полей. Наша цель все-таки — научиться документировать.
2. Не будем пытаться соблюсти все паттерны проектирования API и следовать best practices. Наша цель — см. П1.
3. Не будем описывать схему и принципы авторизации. Про цель вы в курсе :), да?
4. Не будем останавливаться на каких-то базовых вещах типа установки git на компьютер, настройки рабочего окружения и, глубокой теории по технологиям и инструментам. Но если будут возникать вопросы, будем стараться решать их вместе.
Про периодичность публикации постов. Не буду публиковать их часто: не более двух постов из курса в неделю, чтобы все смогли в нормальном темпе переваривать информацию и разбираться с возникающими вопросами.
Посты из курса буду помечать хэштегом #apidocs.
Вопросы, жалобы, предложения?
Следующий пост будет в четверг, 26.09: займемся описанием и проектированием сущностей API.
До встречи.
👍16🔥11❤2
#apidocs
Привет. Продолжаем курс по документированию API.
Сегодня займемся проектированием ресурсов (сущностей).
Если кратко, ресурс в API — это сущность, с которой можно взаимодействовать через API. В нашем API это — «Технический писатель» и «Навык»
Ранее мы определили, что будем работать со следующими ресурсами:
- Технический писатель. Поля: ID, имя, отчество, фамилия, опыт работы, список навыков (скиллов), контактные данные.
- Навык: ID, название навыка, алиас, описание навыка, подтверждающий документ, ссылки на примеры.
Для проектирования можно использовать таблицы (это удобно, согласитесь?).
Спроектируем ресурс «Технический писатель»:
Структура ресурса:
Что здесь нужно пояснить:
1. Запомните, что ресурс в API — это не то же самое, что хранится в базе данных (проектирование БД — отдельный разговор). Т.е. одна сущность, которой мы оперируем в API, может как матрешка собираться из нескольких таблиц.
2. Тип данных для id в нашем случае — целое число. Но часто используют строковый формат: все из-за простоты его сериализации (если интересно можно углубиться в особенности работы сданными в разных языках). При это, если в API id — строка, это не значит, что в базе данных он тоже хранится в виде строки.
3. Для типа данных string в спецификации еще можно указать формат. Об этом — в следующих уроках.
4. Список скиллов в ресурсе — это массив идентификаторов скиллов. Можно их указать и в другом виде, например в виде массива объектов, или ссылок. В любом случае, чтобы, например, все вывести на фронте (информацию про нашего техписа и про его скиллы, «под капотом» будет «дергаться» не один метод).
5. Контактные данные можно представить в виде массива с разными полями (телефон, сайт, канал в Телеграм и пр.). Но не будет усложнять. Пусть у нас будет 2 отдельных поля, одно из которых должно будет заполнено обязательно при добавлении в базу нового техписа.
По аналогии спроектируем ресурс «Навык»:
Что здесь нужно пояснить:
1. Поле «Подтверждающий документ» с типом string. В нашем случае это будет ссылка на изображение диплома, сертификата и пр.
2. Поле «Ссылки на примеры» с типом array(string). В нашем случае это будет массив со ссылками на примеры работ по данному навыку.
Что дальше? А дальше, имея представление о ресурсах и перечень действий, которые можно будет с ними выполнить, можно приступать к подготовке OpenAPI спецификации для нашего API.
Этим займемся в следующий раз.
А перед этим рекомендую ознакомиться с OpenAPI Specification v3.1.0 (хотя бы вскользь).
Привет. Продолжаем курс по документированию API.
Сегодня займемся проектированием ресурсов (сущностей).
Если кратко, ресурс в API — это сущность, с которой можно взаимодействовать через API. В нашем API это — «Технический писатель» и «Навык»
Ранее мы определили, что будем работать со следующими ресурсами:
- Технический писатель. Поля: ID, имя, отчество, фамилия, опыт работы, список навыков (скиллов), контактные данные.
- Навык: ID, название навыка, алиас, описание навыка, подтверждающий документ, ссылки на примеры.
Для проектирования можно использовать таблицы (это удобно, согласитесь?).
Спроектируем ресурс «Технический писатель»:
Структура ресурса:
|Название поля|Имя поля в API|Тип данных|
|-------------|--------------|----------|
|Идентификатор|id|integer|
|Фамилия|secondName|string|
|Имя|firstName|string|
|Отчество|patronymic|string|
|Опыт работы|experience|integer|
|Список скиллов|skills|array(integer)|
|Телефон|phone|string|
|Электронная почта|email|string|
Что здесь нужно пояснить:
1. Запомните, что ресурс в API — это не то же самое, что хранится в базе данных (проектирование БД — отдельный разговор). Т.е. одна сущность, которой мы оперируем в API, может как матрешка собираться из нескольких таблиц.
2. Тип данных для id в нашем случае — целое число. Но часто используют строковый формат: все из-за простоты его сериализации (если интересно можно углубиться в особенности работы сданными в разных языках). При это, если в API id — строка, это не значит, что в базе данных он тоже хранится в виде строки.
3. Для типа данных string в спецификации еще можно указать формат. Об этом — в следующих уроках.
4. Список скиллов в ресурсе — это массив идентификаторов скиллов. Можно их указать и в другом виде, например в виде массива объектов, или ссылок. В любом случае, чтобы, например, все вывести на фронте (информацию про нашего техписа и про его скиллы, «под капотом» будет «дергаться» не один метод).
5. Контактные данные можно представить в виде массива с разными полями (телефон, сайт, канал в Телеграм и пр.). Но не будет усложнять. Пусть у нас будет 2 отдельных поля, одно из которых должно будет заполнено обязательно при добавлении в базу нового техписа.
По аналогии спроектируем ресурс «Навык»:
|Название поля|Имя поля в API|Тип данных|
|-------------|--------------|----------|
|Идентификатор|id|integer|
|Название навыка|skillName|string|
|Описание навыка|skillDescription|string|
|Алиас|alias|string|
|Подтверждающий документ|confirmingDocument|string|
|Ссылки на примеры|linksExamples|array(string)|
Что здесь нужно пояснить:
1. Поле «Подтверждающий документ» с типом string. В нашем случае это будет ссылка на изображение диплома, сертификата и пр.
2. Поле «Ссылки на примеры» с типом array(string). В нашем случае это будет массив со ссылками на примеры работ по данному навыку.
Что дальше? А дальше, имея представление о ресурсах и перечень действий, которые можно будет с ними выполнить, можно приступать к подготовке OpenAPI спецификации для нашего API.
Этим займемся в следующий раз.
А перед этим рекомендую ознакомиться с OpenAPI Specification v3.1.0 (хотя бы вскользь).
🔥6❤2👍1
#apidocs
Привет. Продолжаем курс по документированию API.
Сегодня посмотрим, как описываются методы API в формате Open API. Т.е. после занятия у нас уже будет документация, которую можно показывать разработчикам.
Для описания API будем использовать спецификацию OpenAPI v3.0.0. Почему не более v3.1.0 свежую от 2021 года? v3.0.0 хоть и была опубликована в 2017 году, ее и сейчас «по инерции» используют многие. К тому же и некоторые привычные всем инструменты (например, Swagger Editor) «ругаются» на v3.1.0.
В одном из следующих уроков обязательно рассмотрим разницу между этими версиями спецификации.
Описывать API можно в формате YAML или JSON: как вам удобно. В курсе будем использовать YAML.
Итак, писать спецификацию на API в формате OpenAPI v3.0.0 можно с помощью разных инструментов. Выбирайте удобный:
- https://editor.swagger.io/ — онлайн-редактор из состава экосистемы инструментов «Swagger».
- https://app.swaggerhub.com/ — тоже онлайн-редактор. Нужна регистрация. На бесплатном аккаунте можно создавать и публиковать до трех описаний API.
- Плагин OpenAPI (Swagger) Editor для VS Code — редактор со Swagger UI прямо в IDE.
Давайте рассмотрим создание описания API в формате OpenAPI на примере метода для получения информации об одном техническом писателе.
Ресурс «Технический писатель» мы спроектировали на предыдущем уроке. Теперь давайте опишем в формате OpenAPI его и метод для получения одного техписа (одного ресурса).
Спецификация в формате OpenAPI — это один большой объект (он же — схема), который состоит из полей и объектов поменьше (они, в свою очередь тоже состоят из объектов).
Состав «корневого» объекта описан в спецификации (https://spec.openapis.org/oas/v3.0.0#fixed-fields). Видно, что часть объектов здесь обязательная, а часть — нет.
Мы в курсе будем использовать следующие из них:
-
-
-
-
-
Теперь рассмотрим это на конкретном примере.
По ссылке размещен фрагмент спецификации на наш API, в которой описан метод для получения информации об одном техническом писателе.
Вы можете скопировать ее в любой из указанных выше инструментов и посмотреть, как это все работает.
Кратко поясняю, что здесь происходит:
- Строка 1. В объекте оpenapi указано, что документация на API подготовлена в формате OpenAPI v3.0.0.
- Строки со 2 по 12. В объекте info указана основная информация про API: краткой и развернутое описание и версия. Здесь можно использовать, например, html-теги, чтобы в Swagger UI или на статическом сайте это выглядело красиво и удобочитаемо.
- Строки с 13 по 15. В объекте tags указан (это) пока, один тег для группировки методов в документации.
- Строка 16. Отсюда начинается описание методов (конечных точек).
- Строки с 17 по 43. Здесь описан метод для получения информации об одном техническом писателе /techwriters/{techwriterId}.
- Строка 44. Отсюда начинается объект components.
- Строки с 46 по 94 — здесь описан ресурс (объект) Techwriter, который возвращается в ответе метода для получения информации об одном техническом писателе /techwriters/{techwriterId} (на этот ресурс есть ссылка из описания метода в строке 39).
- На закомментированные строки с 95 по 98 внимания не обращайте. Этот объект автоматически сгенерирован сервисом https://app.swaggerhub.com/.
Привет. Продолжаем курс по документированию API.
Сегодня посмотрим, как описываются методы API в формате Open API. Т.е. после занятия у нас уже будет документация, которую можно показывать разработчикам.
Для описания API будем использовать спецификацию OpenAPI v3.0.0. Почему не более v3.1.0 свежую от 2021 года? v3.0.0 хоть и была опубликована в 2017 году, ее и сейчас «по инерции» используют многие. К тому же и некоторые привычные всем инструменты (например, Swagger Editor) «ругаются» на v3.1.0.
В одном из следующих уроков обязательно рассмотрим разницу между этими версиями спецификации.
Описывать API можно в формате YAML или JSON: как вам удобно. В курсе будем использовать YAML.
Итак, писать спецификацию на API в формате OpenAPI v3.0.0 можно с помощью разных инструментов. Выбирайте удобный:
- https://editor.swagger.io/ — онлайн-редактор из состава экосистемы инструментов «Swagger».
- https://app.swaggerhub.com/ — тоже онлайн-редактор. Нужна регистрация. На бесплатном аккаунте можно создавать и публиковать до трех описаний API.
- Плагин OpenAPI (Swagger) Editor для VS Code — редактор со Swagger UI прямо в IDE.
Давайте рассмотрим создание описания API в формате OpenAPI на примере метода для получения информации об одном техническом писателе.
Ресурс «Технический писатель» мы спроектировали на предыдущем уроке. Теперь давайте опишем в формате OpenAPI его и метод для получения одного техписа (одного ресурса).
Спецификация в формате OpenAPI — это один большой объект (он же — схема), который состоит из полей и объектов поменьше (они, в свою очередь тоже состоят из объектов).
Состав «корневого» объекта описан в спецификации (https://spec.openapis.org/oas/v3.0.0#fixed-fields). Видно, что часть объектов здесь обязательная, а часть — нет.
Мы в курсе будем использовать следующие из них:
-
оpenapi — обязательное поле. Здесь указывается, версия спецификации OpenAPI, в которой описывается API.-
info — обязательный объект. Здесь указывается информация непосредственно о нашем API (описание, версия и т.д.)-
tags — необязательный. Используется для группировки методов API. Это нужно, например, для того, чтобы разработчики и пользователи API могли лучше ориентироваться в документации.-
paths — обязательный объект. Здесь описываются конечные точки (методы) API.-
components — необязательный объект. Здесь описываются повторно используемые компоненты, которые могут быть использованы в различных частях документации.Теперь рассмотрим это на конкретном примере.
По ссылке размещен фрагмент спецификации на наш API, в которой описан метод для получения информации об одном техническом писателе.
Вы можете скопировать ее в любой из указанных выше инструментов и посмотреть, как это все работает.
Кратко поясняю, что здесь происходит:
- Строка 1. В объекте оpenapi указано, что документация на API подготовлена в формате OpenAPI v3.0.0.
- Строки со 2 по 12. В объекте info указана основная информация про API: краткой и развернутое описание и версия. Здесь можно использовать, например, html-теги, чтобы в Swagger UI или на статическом сайте это выглядело красиво и удобочитаемо.
- Строки с 13 по 15. В объекте tags указан (это) пока, один тег для группировки методов в документации.
- Строка 16. Отсюда начинается описание методов (конечных точек).
- Строки с 17 по 43. Здесь описан метод для получения информации об одном техническом писателе /techwriters/{techwriterId}.
- Строка 44. Отсюда начинается объект components.
- Строки с 46 по 94 — здесь описан ресурс (объект) Techwriter, который возвращается в ответе метода для получения информации об одном техническом писателе /techwriters/{techwriterId} (на этот ресурс есть ссылка из описания метода в строке 39).
- На закомментированные строки с 95 по 98 внимания не обращайте. Этот объект автоматически сгенерирован сервисом https://app.swaggerhub.com/.
4🔥4❤1🆒1
(продолжение предыдущего поста #apidocs)
Посмотреть, что получилось, можно здесь.
Теперь у нас уже есть какая-то документация (один из видов документации) на API для работы с базой технических писателей. И ее можно показывать разработчикам.
Что дальше? В следующих уроках опишем остальные методы, рассмотрим разницу между описаниями API в формате OpenAPI v3.0.0 и OpenAPI v3.1.0, а затем будем генерировать и кастомизировать статический сайт-справочник (еще один вид документации на API).
Описание этапа получилось краткое. Если у вас есть вопросы, готов ответить. Пишите в комментариях к посту или в личку.
Посмотреть, что получилось, можно здесь.
Теперь у нас уже есть какая-то документация (один из видов документации) на API для работы с базой технических писателей. И ее можно показывать разработчикам.
Что дальше? В следующих уроках опишем остальные методы, рассмотрим разницу между описаниями API в формате OpenAPI v3.0.0 и OpenAPI v3.1.0, а затем будем генерировать и кастомизировать статический сайт-справочник (еще один вид документации на API).
Описание этапа получилось краткое. Если у вас есть вопросы, готов ответить. Пишите в комментариях к посту или в личку.
Swaggerhub
Build, Collaborate & Integrate APIs | SwaggerHub
Join thousands of developers who use SwaggerHub to build and design great APIs. Signup or login today.
2🔥4👍2
Делаем статический сайт с материалами по курсу #apidocs?
Anonymous Poll
96%
Да.
2%
Нет.
2%
Какой еще курс?
PRO_техписательство
Приехал-таки мой диплом. Теперь официально: технический писатель системный аналитик.
В комментариях вы просили отдельный пост про обучение в «Нетологии»?
Держите отдельную статью.
Держите отдельную статью.
Хабр
Очередной обзор очередного курса. Или как техпис на системного аналитика в «Нетологии» учился
Привет, Хабр. Знаю, что здесь куча обзоров на различные курсы от разных школ, платформ и иже с ними. Но все-таки хочу вставить и свои 5 копеек. Рассказываю о своих ощущениях от курса «Системный...
🔥3👏3
#apidocs
Наступил вечер пятницы, а наш API обзавелся новыми методами для получения нужной информации.
Актуальные для данного этапа спецификации — на Gitlab и SwaggerHub.
Подробности и пояснения по некоторыми моментам — после выходных. И ответы на вопросы, если за выходные они у вас появятся.
Наступил вечер пятницы, а наш API обзавелся новыми методами для получения нужной информации.
Актуальные для данного этапа спецификации — на Gitlab и SwaggerHub.
Подробности и пояснения по некоторыми моментам — после выходных. И ответы на вопросы, если за выходные они у вас появятся.
👍3❤2🤝2🔥1