Привет, сегодня понедельник, 23.09, а значит, пора начинать наш мини-курс по проектированию API.

Итак, тренироваться будем на кошках техписах.
В рамках курса мы спроектируем и задокументируем API (REST like, не побоюсь этого слова) в соответствии с ТЗ:

Цель: Разработать API для управления базой данных о технических писателях и их навыках.

Сущности, которыми будет оперировать API:
Технический писатель. Поля: ID, имя, отчество, фамилия, опыт работы, список навыков (скилл), контактные данные.
Навык: ID, название навыка, алиас, описание навыка, подтверждающий документ, ссылки на примеры.

Действия, которые будут реализованы в API:
- Получение списка технических писателей.
- Получение списка скиллов.
- Получение информации о техническом писателе по идентификатору.
- Получение информации о навыке.
- Добавление нового технического писателя.
- Редактирование сведений о техническом писателе.
- Удаление технического писателя.
- Добавление нового навыка.
- Редактирование навыка.
- Удаление навыка.

А теперь правила, ограничения, условия:

1. Не будем запихивать в сущности кучу полей. Наша цель все-таки — научиться документировать.
2. Не будем пытаться соблюсти все паттерны проектирования API и следовать best practices. Наша цель — см. П1.
3. Не будем описывать схему и принципы авторизации. Про цель вы в курсе :), да?
4. Не будем останавливаться на каких-то базовых вещах типа установки git на компьютер, настройки рабочего окружения и, глубокой теории по технологиям и инструментам. Но если будут возникать вопросы, будем стараться решать их вместе.

Про периодичность публикации постов. Не буду публиковать их часто: не более двух постов из курса в неделю, чтобы все смогли в нормальном темпе переваривать информацию и разбираться с возникающими вопросами.

Посты из курса буду помечать хэштегом #apidocs.

Вопросы, жалобы, предложения?

Следующий пост будет в четверг, 26.09: займемся описанием и проектированием сущностей API.

До встречи.

#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). Видно, что часть объектов здесь обязательная, а часть — нет.

Мы в курсе будем использовать следующие из них:
- о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/.

(продолжение предыдущего поста #apidocs)

Посмотреть, что получилось, можно здесь.

Теперь у нас уже есть какая-то документация (один из видов документации) на API для работы с базой технических писателей. И ее можно показывать разработчикам.

Что дальше? В следующих уроках опишем остальные методы, рассмотрим разницу между описаниями API в формате OpenAPI v3.0.0 и OpenAPI v3.1.0, а затем будем генерировать и кастомизировать статический сайт-справочник (еще один вид документации на API).

Описание этапа получилось краткое. Если у вас есть вопросы, готов ответить. Пишите в комментариях к посту или в личку.

В комментариях вы просили отдельный пост про обучение в «Нетологии»?
Держите отдельную статью.

#apidocs

Наступил вечер пятницы, а наш API обзавелся новыми методами для получения нужной информации.
Актуальные для данного этапа спецификации — на Gitlab и SwaggerHub.

Подробности и пояснения по некоторыми моментам — после выходных. И ответы на вопросы, если за выходные они у вас появятся.

#apidocs

Привет.
Продолжаем курс по документированию 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. Оставайтесь на связи.

Что-то давно стихов IT-шных у нас не было.
Придумалось вот за рулем:

На проде аффектится импорт.
На «тесте» регресс не прошел.
Я «фича» ребейзнул — конфликты.
QA новый баг вдруг нашел.

Тимлид мой МР не аппрувит.
Тех. дир вдруг позвал уан ту уан.
Стажер, блин, скиллы не импрувит.
На кой мне такой падаван?

#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. Нужно просто обернуть спецификацию в теги

@startyaml  @endyaml 

и она отрисуется в виде картинки. Но есть нюанс: некоторые плагины PlantUML не понимают символ «|» в YAML (используется для многострочных блоков текста). Поэтому спецификацию нужно предварительно подготовить: убрать «|», блоки сделать в одну строку и убрать из них служебные символы (т.к. в этом случае уже будет «ругаться» YAML). Посмотреть, как это выглядит, можно, открыв в вашей IDE этот файл. Но у вас должно быть установлено расширение для работы с PlantUML (я использую VSCode и расширение PlantUML для него). Возможно, с вашим плагином (если будете использовать что-то другое) такого не случится, кто знает :).

Теперь, у нас уже есть одна из форм документации API — спецификация в формате OpenAPI.

Что дальше? А дальше мы будем генерить из нее статический сайт-справочник (не без docs as code, конечно же).

Будьте на связи.

#apidocs

Привет.
Продолжаем курс по документированию API.

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

Обещал дать некоторые пояснения по итоговой спецификации. Даю:

1️⃣ У кого-то может возникнуть вопрос, почему в Schemas гораздо больше схем, чем ресурсов, которые мы определили/спроектировали ранее. Так вот, здесь размещаются не только описания ресурсов, но и модели данных, которыми оперируют методы API: структуры запросов, ответов и т.д. — все, что отправляется и передается, переиспользуется и пр.
2️⃣ Почему для изменения ресурсов мы используем метод PATCH, если есть еще PUT? Действительно, изменять ресурс можно PATCH и PUT-методами. Но стандарты HTTP рекомендуют использовать PUT для полной замены или перемещения ресурса (подробнее). Т.е. если бы мы использовали PUT, то каждый раз при изменении данных, например, техписа или навыка, нужно было бы передавать полный набор полей. При использовании PATCH же можно передать только те поля, которые нужно перезаписать.

Пожалуй, все. Если еще что-то не понятно, обращайтесь.

Что дальше? А дальше будем собирать статический справочник из нашей спецификации с помощью Foliant. Перед этим рекомендую вам форкнуть репозиторий с заготовкой, установить на своей компьютере Docker, прочесть Readme в указанном репозитории (там информации не очень много) и, по желанию, выполнить локальную сборку (а может даже и деплой), как там описано.

#apidocs

Привет. Продолжаем наш курс.
Сегодня сделаем магию — соберем статический сайт-справочник 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, оставляйте ссылки в комментариях.

Сегодня пост не по теме курса.
Попалась классная статья про GraphQL — прямо то, что нужно для старта и погружения.
Ох, если бы она была тогда, когда мне пришлось вникать в GraphQL.
В общем, категорически рекомендую.

Я только сегодня осознал, что Айтишечка преследовала меня всегда и пыталась засосать в себя. И засосала-таки

На пятом курсе военной академии я выбрал тему диплома «Разработка интерактивного тренажера для обучения личного состава работе с аппаратной … (дальше секретно)». Это была программа (если ее так можно назвать вообще), разработанная с помощью 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. И теперь я понимаю, что это надолго. Ведь это то, чего я хотел: некий симбиоз писателя, программиста и еще каких-то там айтишных специальностей.

Все-таки Айтишечка добилась своего — она меня засосала. И это чертовски приятно осознавать.

#apidocs

Привет.
Публикую очередной (и завершающий) урок курса по документированию 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. Если есть такое желание, пишите в комментариях.

Итоги года (а как же без них?):

- Попробовал себя в роли спикера. Выступил на TW Days 1 и мне понравилось (надеюсь, что слушателям тоже). Готовлю доклад для TW Days 2.
- Довольно много путешествовал с семьей на авто (за год около 35 000 км пробега получилось).
- Получил диплом системного аналитика. И даже поработал несколько месяцев СА.
- Сменил работу (получилось как-то внезапно, спонтанно, внепланово). Пока нравится.
- Купип сапборд. Доволен как слон. Правда, во время последнего в сезоне заплыва утопил очки👓.
- Получил 336 новых подписчиков на канал. Пожалуй, это один из главных и значимых для меня итогов: значит, кому-то интересна моя писанина. Спасибо за то, что читаете канал. В следующем году постараюсь радовать подписчиков новыми интересными и полезными постами (почаще).

С наступающим 2025 годом!!! Всем желаю «сбычи мечт», чтобы список итогов в 2025 году был длинным и состоял только из приятных пунктов.

Решил размяться перед первым рабочим днем и доделать презентацию к докладу на TW Days 2.
Тяжеловато, скажу я вам, запускается мозг после продолжительных праздников.
Надеюсь, кураторам доклад зайдет.

Осталось всего 2 месяца до TechWriter Days #2. Программа уже сформирована. Интересных докладов будет много. Потихоньку формирую для себя список тех, на которые пойду.