Привет, Хабр.

В статье расскажу про Foliant и про возможности по документированию HTTP API с его использованием. Упор сделаю на API, которые описываются с помощью OpenAPI/Swagger. Также вскользь коснусь возможностей по документированию API, описанных с помощью других спецификаций.

А чтобы вам было легче стартануть, поделюсь ссылкой на стартерпак, который поможет быстро наладить сборку статического справочника HTTP API с помощью Foliant и его деплой на Gitlab Pages.

Статья написана по мотивам моего доклада на конференции Techwriter Days #1, прошедшей с 5 по 6 апреля 2024 г. Это не инструкция. Скорее — обзор возможностей Foliant и способов его применения при документировании API.

Один из способов документирования HTTP API — справочники в виде статических сайтов с овервью, информацией по авторизации, описаниями методов, примерами запросов, ответов и прочей информацией.

Плюсы этого типа документации:

• Статические сайты легко размещать. Ими просто управлять.

• Со справочником может работать любой: не нужно ходить на стенд со Swagger UI и дергать там какие-то API-ручки (ведь доступы к таким стендам есть не всегда).

• На таком сайте можно разместить всю необходимую информацию по API и даже больше, чем есть, например в OpenAPI-спецификации.

Подготовка таких справочников, как правило, ложится на плечи технического писателя (ну или техписа, работающего в паре с DevOps или DocOps).

И тут он может столкнуться с некоторыми «вызовами»:

• В системе может быть много компонентов (микросервисов).

• У всех этих компонентов свой API. Или вообще, у системы может быть несколько API для разных внешних «потребителей».

• У каждой команды разработки спецификации API описаны по-разному: есть просто спецификации или ТЗ на разработку, есть OpenAPI, RAML или другая спецификация, или же есть просто комментарии в коде.

При этом в большинстве случаев все хотят видеть удобные для восприятия справочники по всем HTTP API, с которыми приходится взаимодействовать.

А еще кто-то хочет видеть документацию в разных форматах: не только в виде сайта-справочника, но и еще в PDF и DOCX.

Как быть техническому писателю?

Конечно же, хочется найти инструмент, который бы позволил формировать единообразные и удобные справочники, независимо от того, что мы имеем в качестве исходных данных.

И такой инструмент есть. Это — Foliant.

Что такое Foliant

Foliant — это издательская система для создания документации в разных форматах (статический сайт, PDF, документы Word и т.д.) с поддержкой принципа одного источника.

Это opensource инструмент «высокого уровня». Внутри себя он использует для генерации документации другие opensource инструменты (в Foliant они называются «бэкендами»). В качестве бэкендов, в частности, используются SSG (генераторы статических сайтов), которые получают на вход маркдаун-файлы и выдают документацию в виде статических сайтов.

На картинке выше изображена максимально упрощенная схема архитектуры Foliant. Здесь мы видим ядро, конфигурационный слой, бэкенды и препроцессоры. В контексте данной статьи нас интересуют в первую очередь бэкенды и препроцессоры. Дальше углубляться не будем.

Бэкенды Foliant

Бэкенды — opensource инструменты, которые получают на вход маркдаун-файлы и выдают документацию в нужном формате.

Примеры бэкендов, которые используются в Foliant:

• MkDocs — для генерации порталов с документацией.

• Pandoc — для генерации документации в формате PDF или DOCX.

• Slate — для генерации сайтов-справочников API и БД.

Не бэкендами едиными

Одна из основных «фишек» Foliant — препроцессоры. Они запускаются перед бэкендами и определенным образом обрабатывают файлы, чтобы они стали понятными этим самым бэкендам.

Препроцессоры могут выполнять разные задачи. Например:

• Преобразовывать данные из одного формата в другой (в частности, в Markdown, понятный бэкендам).

• Рисовать диаграммы (на входе препроцессора — код в определенной нотации, на выходе — изображение).

• Инклюдить информацию из нескольких файлов в один.

• Управлять оформлением и форматированием в файлах Markdown, которые будут скармливаться бэкендам.

Несколько примеров препроцессоров и описание их возможностей — ниже.

Как документировать HTTP API с Foliant

Для документирования HTTP API в Foliant используется бэкенд Slate (не только он, но здесь я рассказываю именно про Slate). Он генерирует справочники API и баз данных в виде одностраничных статических сайтов.

Slate принимает на вход Markdown-файлы, а на выходе формирует статику (HTML, CSS, JS).

Этот бэкенд поддерживает подсветку синтаксиса для более чем 100 языков. Сайты получаются удобными, с чистым интуитивно-понятным дизайном.

Используя Foliant и Slate можно выстроить различные флоу формирования справочников, в зависимости от того, какая входная информация есть по HTTP API. Ниже — описание нескольких кейсов и флоу, которые можно выстроить для их реализации.

Если на проекте есть Swagger (OpenAPI-спецификация)

В таком случае с помощью «Фолианта» можно выстроить следующий флоу создания справочника API:

1. Берем спецификацию.

2. Обрабатываем ее препроцессором SwaggerDoc. Он преобразует спецификацию в Markdown, который будет понятным бэкенду.

3. Скармливаем результат Slate, и получаем на выходе симпатичный одностраничный сайт-справочник.

На рисунке показан пример того, как может выглядеть Slate-сайт с дефолтными настройками (про кастомизацию такого сайта — ниже).

В качестве спецификации я взял известную, если не всем, но многим, спеку Petstore api.

При таком флоу большая часть работы выполняется препроцессором SwaggerDoc. Он берет OpenAPI-спецификацию и преобразует ее в Markdown, который понятен Slate.

Вы можете пробрасывать ему OpenAPI-спецификацию в разных форматах и разными способами:

• в формате JSON,

• в формате YAML,

• расположенную локально,

• лежащую где-то на сервере, в репозитории, каком-то хранилище и т.д.

Если на проекте нет Swagger (OpenAPI-спецификации)

В этом случае флоу будет выглядеть следующим образом:

При таком флоу техписатель:

1. Готовит описания вручную в Маркдауне. Информацию можно брать: из проектных описаний методов, делать запросы к API самостоятельно и добавлять полученную информацию в md-файл, получать ее от разработчиков, аналитиков и других стейкхолдеров. Маркдаун-файл оформляется по определенным правилам, чтобы он был понятен бэкэнду.

2. «Скармливает» Маркдаун-файл бэкенду Slate, и подучает на выходе одностраничный сайт-справочник.

Вот пример оформления такого Маркдаун-файла с описанием методов API:

# Introduction

Welcome to the Kittn API! You can use our API to access Kittn API endpoints, which can get information on various cats, kittens, and breeds in our database.

# Authentication

> To authorize, use this code:

```shell
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "Authorization: meowmeowmeow"
```

### HTTP Request

`GET http://example.com/api/kittens`

### Query Parameters

Parameter | Default | Description
--------- | ------- | -----------
include_cats | false | If set to true, the result will also include cats.

Здесь:

• Заголовок первого уровня используется для обозначения названия группы методов.

• Заголовки второго уровня — для названия групп и методов.

• То, что обозначено знаком > и как код-блок (``` ```) уходит в правую секцию сайта, там где примеры кода.

В остальном же здесь используется привычный нам Маркдаун-синтаксис: поддерживаются таблицы, ссылки и т.д. Подробнее о синтаксисе — в Wiki Slate.

Т.е. в этом кейсе, когда нет Swagger-спеки, отсутствует такое звено, как препроцессор SwaggerDoc. Ведь мы уже имеем Маркдаун-файл, который будет понятен Slate и может быть «скормлен» ему напрямую

Если в один справочник нужно добавить информацию по нескольким API

Если вашей системе много компонентов (микросервисов) и пользователям нужна информация по ним в одном справочнике, Foliant поможет реализовать это. Причем, у каких-то компонентов может быть Swagger, у каких-то — нет. В этом случае придется комбинировать рассмотренные выше подходы:

В одном Маркдаун-файле можно написать описание, понятное для Slate вручную. В другом — можно разместить описание, которое спарсили из комментариев в коде (процесс парсинга и формирования таких сайтов — отдельная тема). Также можно добавить md-файл с одним или несколькими тегами препроцессора SwaggerDoc.

Все это дело склеится в единое целое и будет обработано бэкендом Slate. На выходе будет сайт-справочник, в котором будет описание сразу нескольких API.

Если есть другие «хотелки» по справочникам API

Конечно же описанными выше кейсами всё не ограничивается. Ситуации и «хотелки» пользователей API-справочников могут быть разными. И здесь раскрывается вся мощь Foliant в виде его препроцессоров. Ниже — краткий обзор нескольких из них. Подробнее обо всех препроцессорах и их возможностях — в документации Foliant.

Препроцессор Replace

Поможет в разных случаях. Например:

• Когда нужно вместо «обезличенных» примеров ответов для метода добавить реалистичные данные. Или, например, хочется добавить пояснения прямо в пример ответа.

• Если требуется изменить описание метода при сборке справочника, расширить какой-то фрагмент текста или вообще удалить (полезно, например, когда у техписа нет доступа к коду, откуда берутся исходники).

• Когда нужно поправить кривую сборку справочника (можно добавить HTML и CSS с помощью этого препроцессора).

Replace поддерживает регулярные выражения. Этот препроцессор «проходится» по Маркдаун-файлам, перед тем, как они будут скормлены Слэйту, и заменяет одни фрагменты текста другими.

Пример настроек препроцессора:

- replace:
	re_dictionary:
		'`(?i)(my_api)`': '[\1](https://www.api_reference.com/)’
		'`(?i)(my_site)`': '[\1](https:// www.my_site.ru)'

Препроцессор APIReferences

Будет полезен, если в справочник API нужно добавить ссылки на другие справочники. Здесь используется определенный синтаксис: достаточно указать метод и префикс справочника, в котором он находится в формате My-API: GET /user/status, и ссылка сформируется при сборке сайта.

Пример настроек препроцессора:

PET-API:
      mode: find_by_tag_content
      url: http://petapi.com/api # адрес справочника API
      content_template: 'Operation {verb} {command}’

Препроцессоры для работы с графикой

В Foliant несколько препроцессоров, с помощью которых можно добавлять графику на сайты-справочники API. Вот некоторые из них:

• Plantuml,

• Mermaid,

• Graphviz.

Они преобразуют код в соответствующей нотации в картинки.

Пример кода для препроцессора Plantuml:

@startuml

skinparam componentStyle rectangle

[Препроцессор\n SwaggerDoc] -> [Slate] : Markdown
[Markdown] --> [Slate] : Markdown
[Парсер]-->[Markdown]
[Исходники в Markdown] --> [Slate] : Markdown
[Slate] -> [Сайт] : HTML, CSS, JavaScript

@enduml

Препроцессор Includes

Будет полезен, если в справочники API нужно добавлять фрагменты из других файлов. Можно вставлять файлы целиком, либо какие-то их части, указав, например, заголовки, между которыми будет взят текст и вставлен, либо id HTML-элементов.

Пример использование препроцессора:

<!-- Вставка файла целиком -->

Ниже — текст из другого файла.
<include src="for_include/chapter.md"></include>

<!-- Вставка файла из другого репозитория -->
Ниже — текст из другого репозитория.
<include url="https://github.com/repo/chapter.md"></include>

Всего в Foliant более 45 препроцессоров под разные нужды. Кроме того, вы можете добавлять сюда и свои препроцессоры, под какие-то специфичные нужды: инструмент ведь это опенсорсный. Инструкция есть на сайте фолианта, понятная и удобная, с конкретным примером.

Кастомизация справочников API

Влиять на внешний вид сайта можно через настройки препроцессора SwaggerDoc или бэкенда Slatе.

Под капотом у SwaggerDoc — тулза Widdershins, которая обрабатывает OpenAPI-спецификацию и выдает Маркдаун-файлы. Собственно, влиять не внешний вид сайта, порядок вывода блоков с информацией вы можете посредствам настройки шаблонов Widdershins. В них используется синтаксис .dot

На слайде пример того, как стандартный шаблон из репозитория Widdershins немного изменили (в частности, английский язык заменили русским, изменили порядок вывода информации и пр.) и получили уже слегка кастомизированный сайт-справочник.

Что касается кастомизации через Slate, ему можно пробросить кастомный CSS и JS, чтобы, например:

• сменить логотип;

• поменять цветовое оформление;

• добавить на сайт какой-то интерактивности (например, подключить Prism.js и аналоги), или прикрепить счетчик посещений, либо навесить авторизацию через JS с обработкой где-то на стороннем сервисе.

В общем, можно по-полной использовать возможности CSS и JS, если вы в этом сильны. Можно творить с сайтом практически все, что угодно, и генерить справочники API с любыми внешним видом и структурой.

Что нужно для сборки справочников API с помощью Foliant

Foliant можно поставить в вашу систему или использовать в Docker. Ниже приведу пример процесса сборки на примере Docker.

Типовой проект, который используется для сборки справочника API в Docker, выглядит следующим образом:

Он содержит элементы:

• src — папка с файлами-исходниками, которые используются при сборке. Сюда мы кладем написанные вручную файлы или те, в которых указаны теги препроцессора SwаggerDoc.

• Docker и Docker-compose файл.

• Файл конфигурации foliant.yaml. Здесь указываются все настройки сборки: перечисляются файлы, из которых будет собираться справочник, указываются препроцессоры и их настройки, настраиваются бэкенды и т.д.

Пример foliant.yaml:

title: slate_site

chapters:
  - api_from_json.md

preprocessors:
    - swaggerdoc:
        spec_path: pet_swagger.json
        mode: widdershins
        environment:
            language_tabs:
                - shell
                - java
            user_templates: !path ./widdershins_templates
    - includes

backend_config:
    slate:
        slug: API
        shards: 
        - !path ./slate_shards/basic

Удобно, когда настройки всех препроцессоров и бэкендов в Foliant вынесены в один файл. При желании можно расзести их и по отдельным файлам.

Как и где собирать справочники API

Здесь уже всё зависит от вашей фантазии, способностей и ресурсов.

Самый примитивный (ну или простой) вариант — руками собирать локально сайт и потом загружать его куда-то на хостинг.

Можно настроить сборку и автоматическую выгрузку артефактов в public на GitLab или GitHub. Причем, это можно автоматизировать: если вы используете спецификацию из кодового репозитория, можно добавить в его пайплайн триггер, который будет запускать пайплайн в вашем репозитории с докой по наступлению какого-то события в «родительском» кодовом репозитории.

Можно автоматизировать это все еще больше, чтобы все происходило на каком-то удаленном сервере. Например, по мерджу/пушу в master, на сервере запускается раннер, который инициирует процедуру сборки: репозиторий клонируется на сервер, там собирается сайт и выкладывается, в папку, из которой резолвится домен с документацией.

Не только OpenAPI (Swagger)

К слову, только сборкой справочников из OpenAPI-спецификаций Foliant не ограничивается. Здесь есть препроцессор для работы со спецификациями в формате RAML. Также есть бэкэнд, который собирает справочники API из спецификаций в формате Blueprint. Он называется Aglio.

Также с помощью того же Slate можно собирать и справочники по GRPC-API. Для этого подходит, например, тулза proto2slate.

Видно, что Фолиант — это про гибкость. Это инструмент, который позволит техпису (или техпису-докопсу) не стушеваться в разных ситуациях и даже успешно комбинировать разные флоу генерации API-документации, формируя для пользователей симпатичные и удобные в использовании справочники API.

Как и обещал, даю обещанную ссылку на стартерпак для сборки справочника API с помощью Foliant.