BosonBeard Feb 5 at 22:31

«16+» или делаем шаблон страницы в XWiki на примере спецификации API

Easy

9 min

2.4K

Tutorial

Пусть вас не смущает надпись: «16+» в заголовке. В статье не будет ни слова о безудержном кутеже с куртизанками за игрой в блэк-джек.

Просто я решил очередной статьей отпраздновать выпуск в свет 16-й версии XWiki – «open-source аналога Confluence» (по мнению её разработчиков).

Сегодня мы сделаем шаблон спецификации API в XWiki, чтобы в будущем нам было легко и удобно его тиражировать.

Статья скорее рассчитана на новичков, поэтому в процессе я немного расскажу об XWiki и наиболее простом способе её установки.

Подготовка
Шаблон описания API
- Создаем наполнение для шаблона
- Настраиваем шаблон
Результат

Подготовка

Если вы знакомы с 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 уже подготовленной вики.

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

Windows – start_xwiki.bat
Linux / Mac – start_xwiki.sh

Возможно консоль будет «ругаться на версию Java»,

XWiki 16 и выше перешла на 17 версию Java, поэтому придется её установить:

Инструкция для Windows 10 (эти инструкции сработали у меня, но вы можете нагуглить что-то еще),
Инструкция по установке и выбору версии в Ubuntu подобных системах.

Если версия Java удовлетворяет минимальным требованиям начнется запуск, когда вы увидите примерно такое сообщение:

Самое время открывать браузер.

Кстати если вместо, той ссылки что выведена в консоль открыть http://localhost:8080/

эффект скорей всего будет тот же самый.

Какое-то время вики потребуется на запуск

Далее мы видим главную страницу:

Чтобы войти кликните на «бургер» в правом верхнем углу. Нажмите на кнопку для входа и в форме авторизации введите:

User: Admin
Password: admin

Давайте сразу переведем вики на русский язык.

Нажмите на бургер, перейдите в раздел
Administer Wiki->Content->Localisation

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

Почти готово, но чтобы наш шаблон спецификации API был поинтересней, давайте установим расширения PlantUML. Он пригодится нам для подготовки диаграммы последовательности UML (sequence diagram).

В админ-панели перейдите в раздел
«Менеджер расширений»->«Расширения».

В строке поиска вбейте «PlantUML»:

И установите его.

У XWiki есть еще много полезных расширений, например Diagrams application (интеграция draw.io) или нумерованные заголовки. Но чтобы не перегружать статью, оставим это на самостоятельное изучение.

Давайте добавим пару кнопок в редактор контента (это необязательно, но полезно).

Перейдите в раздел
«Редактирование» -> «Визуальный редактор»
и исключите из списка кнопки для выравнивания и управления шрифтом:

Должно получиться так:

Остался последний штрих, нам необходимо переключить редактор страниц в режим продвинутого пользователя.

Перейдите в настройки вашего профиля, нажмите на «карандаш»:

В разделе «Тип пользователя» выберите «продвинутый».

Включение продвинутого режима редактирования.

Не забудьте сохранить.
Теперь мы готовы приступать к созданию шаблона.

Шаблон описания API

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

Создаем наполнение для шаблона

Шаблоны страниц – это заранее подготовленные страницы для решения типовых задач. Шаблоны отображаются при создании новой страницы.

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

Детально с процессом создания шаблонов в XWiki можно познакомится в официальной документации.

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

Я знаю, что есть разные способы описать API, но так или иначе страницы в корпоративной вики до сих пор могут использоваться для описания API. Но если кому-то очень любопытно, то Swagger UI тоже можно прикрутить к XWiki

Для начала создадим страницу с каркасом шаблона. В идеальном мире я бы спрятал её в какую-нибудь вложенную страницу, но в учебных целях мы просто создадим её в корне Wiki.

На главной странице нажмите кнопку «Создать». Выберете пустая страница. Дайте странице название API_Template.

Полный текст страницы будет в конце раздела под спойлером.

Давайте создадим каркас страницы.

Для начала добавим оглавление страницы:

Нажмите кнопку «+» и выберите «Оглавление».

Добавим раздел с общим описанием АПИ в виде таблицы.

Нажмите на иконку таблицы и введите следующие настройки:

Заполним поля таблицы и получим примерно такой результат.

Я привык, чтобы таблицы входных и выходных данных отличались стилем от обычных.

Поэтому давайте сохраним результат и зададим стили для будущих таблиц входных и выходных данных.

Если вы не включили режим продвинутого пользователя, то самое время перечитать концовку прошлого раздела.

Перейдите в режим редактирования объектов страницы:

Редактирование объектов страницы в продвинутом режиме.

Добавьте StyleSheetExtension:

Создадим 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;

}

И установите настройки как на изображении ниже:

Не забудьте сохранить.

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

Поэтому для продуктового решения возможно стоит выбрать область применения ко всей Wiki.

Но вернемся к нашему шаблону. Перейдите в режим редактирования.

Давайте создадим еще одну таблицу, но теперь на вкладке дополнительно укажем класс для таблицы.

Теперь таблица с входными параметрами метода отличается от обычной:

Внешний вид таблицы с классом ApiDataTable.

Сделаем аналогично выходные параметры и ошибки.

Далее добавим диаграмму последовательности.

Нажмите кнопку «+» и выберите «Другие макросы», найдите макрос 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

Должно получиться примерно так:

По желанию можно расписать логику диаграммы текстом.

Добавим примеры ответа.

Чтобы создать пример запроса или ответа нажмите кнопку «+» и выберите «Фрагмент кода». Заполните форму, как на скриншоте:

Получим примерно такую красоту:

Осталось добавить таблицу изменений. Обойдемся обычной табличкой:

Осталось только сделать из нашей страницы шаблон.

Настраиваем шаблон

Перейдите в админ панели в раздел «Контент» -> «Шаблоны».

И заполните по аналогии:

Создание провайдера шаблона в админ-панели.

На следующей странице, введите настройки по аналогии:

Мы не будем ограничивать области применения шаблона, оставим это на самостоятельное изучение.

Результат

Давайте проверим наши плоды трудов.

Создайте в корне новую страницу и выберите API template.

В режиме редактирование откроется страница идентичная нашему шаблону:

Давайте заполним демонстрационным примером.

Скриншоты примера страницы по шаблону, спрячу под спойлер.

Hidden text

Полный текст страницы шаблона под спойлером. Вы можете вставить его через кнопку «Исходный код редактора».

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.

Если статья была полезной, буду рад получить позитивную обратную связь.

Tags:

Hubs: