PRO_техписательство

#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. Если есть такое желание, пишите в комментариях.

🔥9👍3🤝1

733 views05:06