![](https://habrastorage.org/getpro/habr/upload_files/aaa/197/366/aaa1973662955c002aafd03dd83d062f.png)
Пусть вас не смущает надпись: «16+» в заголовке. В статье не будет ни слова о безудержном кутеже с куртизанками за игрой в блэк-джек.
Просто я решил очередной статьей отпраздновать выпуск в свет 16-й версии XWiki – «open-source аналога Confluence» (по мнению её разработчиков).
Сегодня мы сделаем шаблон спецификации API в XWiki, чтобы в будущем нам было легко и удобно его тиражировать.
Статья скорее рассчитана на новичков, поэтому в процессе я немного расскажу об XWiki и наиболее простом способе её установки.
Подготовка
Если вы знакомы с XWiki данный раздел можно пропустить и сразу перейти к шаблону.
Как я уже писал выше, XWiki позиционируется, как доступная альтернатива Confluence. и в некоторой степени я могу с этим согласится. Но есть одно большое отличие. XWiki дает пользователю большую силу, а вместе с ней и большую ответственность. Потому что многие вещи можно «допилить» руками. Это и плюс и минус. Из коробки не все может работать идеально. Впрочем, я начал свое знакомство с XWiki с 12 версии и могу смело сказать, что система потихоньку развивается и становится все удобнее.
Но как говорится: «Лучше один раз увидеть». Давайте перейдем к установке.
Установить XWiki можно разными способами.
Для начала необходимо определиться какую версию установить?
Скорее всего ваш выбор упадет на одну из двух версий:
LTS – прошлогодняя как хлеб первого января, но более стабильная. Однако, LTS версия тоже дорабатывается в течение года, просто, как правило без революционных изменений.
Stable – версия в стадии более активной разработки. Позволяет посмотреть новые фичи, но не застрахована от проблем./
На мой взгляд название версий XWiki может немного ввести в заблуждение.
Потому, что под LTS мы часто привыкли понимать, что-то достаточно стабильное и уже многократно протестированное, но на самом деле бывает, что небольшие баги залетают и в минорные релизы.
Мой совет прост, если вы работаете в организации ориентируйтесь на LTS версию. Если хочется совсем стабильной работы, то лучше ориентироваться на момент когда версия будет выглядеть как NN.10.X, например, 15.10.5. Как правило, в этот момент активная разработка уже практически завершена и выкатываются только небольшие фиксы и обновления пакетов.
Поскольку мы сегодня экспериментируем, то мы скачиваем свежую версию Stable (на момент написания статьи – 16.0).
Установить XWiki можно разными способами: через WAR пакет, образ Docker или даже добавив репозиторий в linux дистрибутив.
Но самый простой способ, чтобы поэкспериментировать это скачать zip архив c уже подготовленной вики.
![](https://habrastorage.org/getpro/habr/upload_files/f02/1d5/4a0/f021d54a03f37d11832a692798e45d4b.png)
После того как вы скачали архив, распакуйте его в любое место.
Для запуска необходимо запустить:
Windows – start_xwiki.bat
Linux / Mac – start_xwiki.sh
Возможно консоль будет «ругаться на версию Java»,
![Ошибка запуска XWiki Ошибка запуска XWiki](https://habrastorage.org/getpro/habr/upload_files/5e1/cfb/5f0/5e1cfb5f0ab64cc7e924cd177b2cdb94.png)
XWiki 16 и выше перешла на 17 версию Java, поэтому придется её установить:
Инструкция для Windows 10 (эти инструкции сработали у меня, но вы можете нагуглить что-то еще),
Инструкция по установке и выбору версии в Ubuntu подобных системах.
Если версия Java удовлетворяет минимальным требованиям начнется запуск, когда вы увидите примерно такое сообщение:
![Успешеный запуск Успешеный запуск](https://habrastorage.org/getpro/habr/upload_files/3b1/cc3/d85/3b1cc3d85991d74c40e97bc54ae7ae25.png)
Самое время открывать браузер.
Кстати если вместо, той ссылки что выведена в консоль открыть http://localhost:8080/
эффект скорей всего будет тот же самый.
Какое-то время вики потребуется на запуск
![Подготовка к запуску Подготовка к запуску](https://habrastorage.org/getpro/habr/upload_files/ab9/e08/34b/ab9e0834baeeb4feeb153abaa7725394.png)
Далее мы видим главную страницу:
![Главная страница Главная страница](https://habrastorage.org/getpro/habr/upload_files/3f4/b26/cd8/3f4b26cd831107bb30d736b2f1b25b15.png)
Чтобы войти кликните на «бургер» в правом верхнем углу. Нажмите на кнопку для входа и в форме авторизации введите:
User: Admin
Password: admin
Давайте сразу переведем вики на русский язык.
Нажмите на бургер, перейдите в раздел Administer Wiki->Content->Localisation
и выберите русский язык по умолчанию (не забудьте сохранить страницу).
![Изменение языка Изменение языка](https://habrastorage.org/getpro/habr/upload_files/0bc/bbd/16d/0bcbbd16dd370ef5d40d6291e2ada63a.png)
Почти готово, но чтобы наш шаблон спецификации API был поинтересней, давайте установим расширения PlantUML. Он пригодится нам для подготовки диаграммы последовательности UML (sequence diagram).
В админ-панели перейдите в раздел «Менеджер расширений»->«Расширения»
.
В строке поиска вбейте «PlantUML»:
![Установка PlantUML Установка PlantUML](https://habrastorage.org/getpro/habr/upload_files/531/6da/495/5316da49529fb9cdd2b3ec5cbe1820ed.png)
И установите его.
У XWiki есть еще много полезных расширений, например Diagrams application (интеграция draw.io) или нумерованные заголовки. Но чтобы не перегружать статью, оставим это на самостоятельное изучение.
Давайте добавим пару кнопок в редактор контента (это необязательно, но полезно).
Перейдите в раздел
«Редактирование» -> «Визуальный редактор»
и исключите из списка кнопки для выравнивания и управления шрифтом:
![Убираем скрытые элементы редактора. Убираем скрытые элементы редактора.](https://habrastorage.org/getpro/habr/upload_files/517/361/03d/51736103da292d38fa8e0dc0bcb00586.png)
Должно получиться так:
![Итоговый вариант. Итоговый вариант.](https://habrastorage.org/getpro/habr/upload_files/45e/ee8/eeb/45eee8eeb1bac113e2fbff0f8b038401.png)
Остался последний штрих, нам необходимо переключить редактор страниц в режим продвинутого пользователя.
Перейдите в настройки вашего профиля, нажмите на «карандаш»:
![Редактирование профиля Редактирование профиля](https://habrastorage.org/getpro/habr/upload_files/88f/099/764/88f0997647bd6251039a067dbbea5e59.png)
В разделе «Тип пользователя» выберите «продвинутый».
![Включение продвинутого режима редактирования. Включение продвинутого режима редактирования.](https://habrastorage.org/getpro/habr/upload_files/1af/29e/67a/1af29e67af8ebf37a9b9a1634e41d960.png)
Не забудьте сохранить.
Теперь мы готовы приступать к созданию шаблона.
Шаблон описания API
Сразу оговорюсь, мы создаем простенький шаблон, исключительно в целях демонстрации. Рекомендую его вам потом доработать под себя.
Создаем наполнение для шаблона
Шаблоны страниц – это заранее подготовленные страницы для решения типовых задач. Шаблоны отображаются при создании новой страницы.
![Шаблоны для новых страниц. Шаблоны для новых страниц.](https://habrastorage.org/getpro/habr/upload_files/886/7ae/284/8867ae28460dc7014aefb7fe9e8458df.png)
Наша задача, добавить к этому списку свой шаблон, который поможет аналитикам или техническим писателям быстрее подготавливать спецификацию API.
Детально с процессом создания шаблонов в XWiki можно познакомится в официальной документации.
Мы сегодня не будем копать очень глубоко и рассмотрим минимально необходимый набор действий.
Я знаю, что есть разные способы описать API, но так или иначе страницы в корпоративной вики до сих пор могут использоваться для описания API. Но если кому-то очень любопытно, то Swagger UI тоже можно прикрутить к XWiki
Для начала создадим страницу с каркасом шаблона. В идеальном мире я бы спрятал её в какую-нибудь вложенную страницу, но в учебных целях мы просто создадим её в корне Wiki.
На главной странице нажмите кнопку «Создать». Выберете пустая страница. Дайте странице название API_Template.
Полный текст страницы будет в конце раздела под спойлером.
![Создаем страницу для каркаса шаблона. Создаем страницу для каркаса шаблона.](https://habrastorage.org/getpro/habr/upload_files/8ed/0c8/b67/8ed0c8b67bfa9269168379433c968ca2.png)
Давайте создадим каркас страницы.
Для начала добавим оглавление страницы:
Нажмите кнопку «+» и выберите «Оглавление».
Добавим раздел с общим описанием АПИ в виде таблицы.
Нажмите на иконку таблицы и введите следующие настройки:
![Настройка таблицы. Настройка таблицы.](https://habrastorage.org/getpro/habr/upload_files/daf/b0c/ad1/dafb0cad1573ddc1ece2fe5fdb658d83.png)
Заполним поля таблицы и получим примерно такой результат.
![](https://habrastorage.org/getpro/habr/upload_files/e1d/11c/bd9/e1d11cbd99381f6a70899498757404d7.png)
Я привык, чтобы таблицы входных и выходных данных отличались стилем от обычных.
Поэтому давайте сохраним результат и зададим стили для будущих таблиц входных и выходных данных.
Если вы не включили режим продвинутого пользователя, то самое время перечитать концовку прошлого раздела.
Перейдите в режим редактирования объектов страницы:
![Редактирование объектов страницы в продвинутом режиме. Редактирование объектов страницы в продвинутом режиме.](https://habrastorage.org/getpro/habr/upload_files/c4f/f51/649/c4ff5164975a4f59b4b94cee322ad946.png)
Добавьте StyleSheetExtension:
![Поиск дополнения CSS Поиск дополнения CSS](https://habrastorage.org/getpro/habr/upload_files/2b8/e18/c06/2b8e18c06e1e4a4e5ef1d843798a9b8f.png)
Создадим CSS классы для таблиц.
Задайте имя для расширения, например, ApiTablesCss.
Для простоты мы добавим только 1 общий класс для таблиц с входными и выходными данными API, но вы сможете потом доработать это расширение по аналогии введите CSS код:
Hidden text
table.ApiDataTable {
text-align: center;
}
table.ApiDataTable tr td:first-child {
text-align: left;
}
table.ApiDataTable tr td:last-child {
text-align: left;
}
table.ApiDataTable td, table.ApiDataTable th {
border: 1px solid #FFFFFF;
padding: 3px 2px;
}
table.ApiDataTable tbody td {
font-size: 13px;
}
table.ApiDataTable thead {
background: #0B6FA4;
border-bottom: 5px solid #FFFFFF;
}
table.ApiDataTable tbody tr th {
background: #0B6FA4;
font-weight: bold;
color: #FFFFFF;
text-align: center;
border-left: 2px solid #FFFFFF;
}
table.ApiDataTable thead th {
font-size: 17px;
background: #0B6FA4;
font-weight: bold;
color: #FFFFFF;
text-align: center;
border-left: 2px solid #FFFFFF;
}
table.ApiDataTable thead th:first-child {
border-left: none;
}
table.ApiDataTable tfoot td {
font-size: 14px;
}
И установите настройки как на изображении ниже:
![Настройки расширения Настройки расширения](https://habrastorage.org/getpro/habr/upload_files/5f6/853/4c1/5f68534c1ed6aff32d8554ee75a2a60e.png)
Не забудьте сохранить.
В данном случае для простоты мы выбрали использовать CSS на этой странице или по запросу. Важно помнить, что с одной стороны так проще сохранить Wiki в чистоте и избежать перезаписи стилей, с другой стороны если вы захотите изменить цвет таблицы во всех существующих страницах. то придется его менять руками в каждой.
Поэтому для продуктового решения возможно стоит выбрать область применения ко всей Wiki.
![Если захотите применить CSS глобально. Если захотите применить CSS глобально.](https://habrastorage.org/getpro/habr/upload_files/a94/980/12f/a9498012fa124c9f4e7ac91a3046d691.png)
Но вернемся к нашему шаблону. Перейдите в режим редактирования.
Давайте создадим еще одну таблицу, но теперь на вкладке дополнительно укажем класс для таблицы.
![Задаем класс таблице. Задаем класс таблице.](https://habrastorage.org/getpro/habr/upload_files/360/e70/013/360e7001305512f01d83680757894918.png)
Теперь таблица с входными параметрами метода отличается от обычной:
![Внешний вид таблицы с классом ApiDataTable. Внешний вид таблицы с классом ApiDataTable.](https://habrastorage.org/getpro/habr/upload_files/c9a/d38/661/c9ad38661395fbad37de2650a6a7c97d.png)
Сделаем аналогично выходные параметры и ошибки.
Далее добавим диаграмму последовательности.
Нажмите кнопку «+» и выберите «Другие макросы», найдите макрос PlantUML и вставьте код:
Hidden text
actor usr as "User"
participant app as "Application"
participant srv as "Backend"
database db as "Database"
autonumber
usr -> app: Some action
app -> srv: Some request
srv -> db: Some request
db --> srv: Some data
srv --> app: Some response
app --> usr: Some result
![Пример макроса PlantUML Пример макроса PlantUML](https://habrastorage.org/getpro/habr/upload_files/366/f02/f99/366f02f992db4258ee89fb2f45ba062d.png)
Должно получиться примерно так:
![Рендеринг диаграммы Рендеринг диаграммы](https://habrastorage.org/getpro/habr/upload_files/7ba/e36/360/7bae36360f2a67ca465ac6c4a4ce5d7d.png)
По желанию можно расписать логику диаграммы текстом.
Добавим примеры ответа.
Чтобы создать пример запроса или ответа нажмите кнопку «+» и выберите «Фрагмент кода». Заполните форму, как на скриншоте:
![Пример макроса «Фрагмент кода» Пример макроса «Фрагмент кода»](https://habrastorage.org/getpro/habr/upload_files/00f/e72/d86/00fe72d86aa7427c6706849fea9bc8a1.png)
Получим примерно такую красоту:
![Примеры запроса и ответов. Примеры запроса и ответов.](https://habrastorage.org/getpro/habr/upload_files/529/a92/914/529a92914e8308bd8dd2c605f6268225.png)
Осталось добавить таблицу изменений. Обойдемся обычной табличкой:
![История изменений. История изменений.](https://habrastorage.org/getpro/habr/upload_files/ee1/033/9e9/ee10339e924452087e37de9bd1bce6d3.png)
Осталось только сделать из нашей страницы шаблон.
Настраиваем шаблон
Перейдите в админ панели в раздел «Контент» -> «Шаблоны».
И заполните по аналогии:
![Создание провайдера шаблона в админ-панели. Создание провайдера шаблона в админ-панели.](https://habrastorage.org/getpro/habr/upload_files/afc/fd3/3d0/afcfd33d0247c8ebd07a6fe1bc7d6f4d.png)
На следующей странице, введите настройки по аналогии:
![Настройка провайдера шаблона. Настройка провайдера шаблона.](https://habrastorage.org/getpro/habr/upload_files/3d9/150/a46/3d9150a464ac5508e7e2570a811483f1.png)
Мы не будем ограничивать области применения шаблона, оставим это на самостоятельное изучение.
Результат
Давайте проверим наши плоды трудов.
Создайте в корне новую страницу и выберите API template.
![Видим наш шаблон в списке. Видим наш шаблон в списке.](https://habrastorage.org/getpro/habr/upload_files/177/8a0/c76/1778a0c767ca7349e108cafe9d9ab93f.png)
В режиме редактирование откроется страница идентичная нашему шаблону:
![Страница создана по шаблону. Страница создана по шаблону.](https://habrastorage.org/getpro/habr/upload_files/245/e09/a02/245e09a02e76b489087c30d8b84afdae.png)
Давайте заполним демонстрационным примером.
Скриншоты примера страницы по шаблону, спрячу под спойлер.
Hidden text
![Часть 1. Часть 1.](https://habrastorage.org/getpro/habr/upload_files/36f/8ed/c74/36f8edc7475dc728e01f030d0128abd5.png)
![Часть 2. Часть 2.](https://habrastorage.org/getpro/habr/upload_files/d26/240/96a/d2624096a789eb645652c50f292c9ffd.png)
![Часть 3. Часть 3.](https://habrastorage.org/getpro/habr/upload_files/1e4/353/c2e/1e4353c2e0fd67f0c589418c921df124.png)
Полный текст страницы шаблона под спойлером. Вы можете вставить его через кнопку «Исходный код редактора».
Hidden text
{{toc/}}
= Описание: =
(% border="0" style="margin-right:auto" %)
|=(% scope="row" %)Метод|//Тип HTTP метода///
|=URL|//URL метода//
|=Применение|//Метод используется //
= Входные параметры =
(% class="ApiDataTable" %)
|=Параметр|=Где расположен|=Тип данных|=Обязательность|=Описание
|Название параметра|//path/query/body//|//укажите тип данных//|//Да / Нет//|//Укажите описание параметра.//
|...|...|...|...|...
= Выходные параметры =
(% class="ApiDataTable" %)
|=Параметр|=Тип данных|=Обязательность|=Описание
|Название параметра|//укажите тип данных//|//Да / Нет//|//Укажите описание параметра.//
|...|...|...|...
= Ошибки метода =
(% class="ApiDataTable" %)
|=Response status|=errorCode|=message|=Описание
|//Код ответа HTTP//|//Код ошибки//|//Текст сообщений//|//Описание ошибки//
|...|...|...|...
= Описание логики =
{{plantuml}}
actor usr as "User"
participant app as "Application"
participant srv as "Backend"
database db as "Database"
autonumber
usr -> app: Some action
app -> srv: Some request
srv -> db: Some request
db --> srv: Some data
srv --> app: Some response
app --> usr: Some result
{{/plantuml}}
= Примеры =
== Пример запроса ==
//Путь к методу и его параметры//
{{code language="json" title="Request"}}
{
"key":"value"
}
{{/code}}
== Пример ответа ==
=== Ответ успех ===
{{code language="json" title="Код 200"}}
{
"key":"value"
}
{{/code}}
=== Ответ с ошибкой ===
{{code language="json" title="Код 400"}}
{
"errorCode":"101",
"message":"Неверные данные",
}
{{/code}}
= История изменений =
|=Дата изменения|=Автор|=Описание|=Задача
|//Дата изменений//|//Автор изменений//|//Описание изменений//|//Ссылка на задачу в таск-трекере (если есть)//
|...|...|...|...
—------------{{toc/}}
= Описание: =
(% border="0" style="margin-right:auto" %)
|=(% scope="row" %)Метод|//Тип HTTP метода///
|=URL|//URL метода//
|=Применение|//Метод используется //
= Входные параметры =
(% class="ApiDataTable" %)
|=Параметр|=Где расположен|=Тип данных|=Обязательность|=Описание
|Название параметра|//path/query/body//|//укажите тип данных//|//Да / Нет//|//Укажите описание параметра.//
|...|...|...|...|...
= Выходные параметры =
(% class="ApiDataTable" %)
|=Параметр|=Тип данных|=Обязательность|=Описание
|Название параметра|//укажите тип данных//|//Да / Нет//|//Укажите описание параметра.//
|...|...|...|...
= Ошибки метода =
(% class="ApiDataTable" %)
|=Response status|=errorCode|=message|=Описание
|//Код ответа HTTP//|//Код ошибки//|//Текст сообщений//|//Описание ошибки//
|...|...|...|...
= Описание логики =
{{plantuml}}
actor usr as "User"
participant app as "Application"
participant srv as "Backend"
database db as "Database"
autonumber
usr -> app: Some action
app -> srv: Some request
srv -> db: Some request
db --> srv: Some data
srv --> app: Some response
app --> usr: Some result
{{/plantuml}}
= Примеры =
== Пример запроса ==
//Путь к методу и его параметры//
{{code language="json" title="Request"}}
{
"key":"value"
}
{{/code}}
== Пример ответа ==
=== Ответ успех ===
{{code language="json" title="Код 200"}}
{
"key":"value"
}
{{/code}}
=== Ответ с ошибкой ===
{{code language="json" title="Код 400"}}
{
"errorCode":"101",
"messagee":"Неверные данные",
}
{{/code}}
= История изменений =
|=Дата изменения|=Автор|=Описание|=Задача
|//Дата изменений//|//Автор изменений//|//Описание изменений//|//Ссылка на задачу в таск-трекере (если есть)//
|...|...|...|...
Также я загрузил шаблон, провайдер шаблонов и пример страницы на GitHub вы можете просто импортировать их в панели администратора в разделе «Контент» -> «Импорт»
Вот так мы совместили приятное с полезным – научились создавать шаблоны и заодно познакомились с обновленным интерфейсом XWiki 16.0.
Если статья была полезной, буду рад получить позитивную обратную связь.