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

#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, оставляйте ссылки в комментариях.