DOCSUP-86795: [DOC] Добавить про openapi во внешнюю доку

ru/changelog.md

@@ -10,11 +10,11 @@ noindex: true
 
 #### 2.0.0
 
-- [Новый интерфейс инклюдеров](./project/toc.md#includers).
-- [Generic инклюдер](./project/toc.md#includers-generic).
-- [Open API инклюдер](./project/toc.md#includers-open-api).
-- [Unarchive инклюдер](./project/toc.md#includers-unarchive).
-- [Source Docs инклюдер](./project/toc.md#includers-source-docs).
+- [Новый интерфейс инклюдеров](./guides/includers.md).
+- [Generic инклюдер](./guides/generic.md).
+- [Open API инклюдер](./guides/openapi.md).
+- [Unarchive инклюдер](./guides/unarchive.md).
+- [Source Docs инклюдер](./guides/source-docs.md).
 
 
 ## Ноябрь 2022
@@ -82,7 +82,7 @@ noindex: true
 
 - include/includers: возможность интеграции сторонних форматов в документацию.
 - include/includers/sourcedocs: возможность интеграции sourcedocs документации в yfm-документацию.
-  [Includers](./project/toc.md#includers)
+  [Includers](./guides/includers.md)
 
 ## Июнь 2022
 

ru/guides/generic.md

@@ -0,0 +1,37 @@
+# Generic
+
+Вы можете сгенерировать документацию в markdown-формате любой утилитой и включить её в основную документацию.
+
+Инклюдер сгенерирует по ней оглавление и включит контент в документацию.
+
+#### Пример использования
+
+Проект документации лежит в `doc_root` папке.
+
+Положим сгенерированный контент в папку `doc_root/docs`.
+
+Включим этот контент с помощью generic-инклюдера в `doc_root/toc.yaml`.
+
+Подключим разводящую в `doc_root/index.yaml`.
+
+```yaml
+# doc_root/toc.yaml
+title: documentation
+href: index.yaml
+items:
+  - name: docs
+    include:
+      path: docs
+      includers:
+        - name: generic
+          input: docs
+      mode: link
+```
+
+```yaml
+# doc_root/index.yaml
+title: documentation
+links:
+  - title: docs
+    href: docs/
+```

ru/guides/includers.md

@@ -0,0 +1,57 @@
+# Вставка произвольного контента (Includers)
+
+Вы можете включить в оглавление произвольный контент через `includers`, но только в случае если `includer` для этого типа контента имплементирован. Список имплементированных инклюдеров можно посмотреть [ниже](#implement-includers).
+
+Возможные способы указания инклюдеров:
+
+- массив `includer`-объектов в поле `includers`;
+
+- `includer`-объект в поле `includer` (_в процессе деприкации в пользу `includers` поля_).
+
+**Требования к `include`:**
+
+1. `include` должен иметь поле `path`, куда контент будет включен.
+
+2. поле `path` должно быть **путем, куда будет включен контент**.
+
+3. свойство `mode` должно иметь значение `link или пропущенно, `link является дефолтным поведением.
+
+**Требования к `includers`:**
+
+`includers` должен быть массивом includer-объектов, которые будут запущенны в указанном порядке.
+
+**Требования к `includer`:**
+
+Параметры между includer-объектами разные, но имя `includer` является обязательным параметром.
+
+`name` указывает имя инклюдера, который запустится.
+
+
+#### Пример использования
+
+Абстрактный пример использования инклюдеров
+
+_Уточненный пример смотрите в разделе соответствуещего инклюдера для конкретного примера использования._
+
+```
+# toc.yaml
+...
+items:
+  - name: <item-name>
+    include:
+      path: <path-where-to-include>
+      includers:
+        - name: <name-of-the-first-includer>
+          <includer-parameter>: <includer-parameter-value>
+        - name: <name-of-the-second-includer>
+        - name: <name-of-the-third-includer>
+      mode: link
+...
+```
+
+## Список имплементированных инклюдеров {#implement-includers}
+
+- [Generic](generic.md);
+- [Open API](openapi.md);
+- [Unarchive](unarchive.md);
+- [Source Docs](source-docs.md) (_в процессе деприкации в пользу generic инклюдера_).

ru/guides/openapi.md

@@ -0,0 +1,193 @@
+# Генерация из OpenAPI-спецификации
+
+Вы можете сгенерировать документ из [OpenAPI-спецификации](https://www.openapis.org/) и включить её в основной документ.
+
+{% note warning %}
+
+Openapi-инклюдер требует разрешение на использование HTML в документации, поэтому внутри конфигурационного файла `.yfm` необходимо указать значение `allowHTML: true`.
+
+{% endnote %}
+
+## Требования к OpenAPI-спецификации
+
+- Версия используемой спецификации не ниже 3.Х.
+- Допускается использование только операторов `oneOf` и `allOf`.
+- Ограничения на использование базового функционала не накладываются.
+
+#### Пример использования
+
+1. Документационный проект лежит в директории `doc_root`.
+
+2. OpenAPI-спецификацию размещаем по пути `doc_root/openapi.yaml`.
+
+3. Включаем её в оглавление `doc_root/toc.yaml` с помощью [openapi-инклюдера](includers.md).
+
+4. Подключаем разводящую в `doc_root/index.yaml`.
+
+```yaml
+# doc_root/toc.yaml
+title: documentation
+href: index.yaml
+items:
+  - name: openapi
+    include:
+      path: openapi
+      includers:
+        - name: openapi
+          input: openapi.yaml
+      mode: link
+```
+
+```yaml
+# doc_root/index.yaml
+title: documentation
+links:
+  - title: openapi
+    href: openapi/
+```
+
+
+### `tags`
+
+Позволяет менять оглавления тегов. Описания конечных точек, полученные после сборки, раскладываются по тегам.
+
+#### Синтаксис
+
+```yaml
+tags:
+    __root__:
+        name: Новое название оглавления на верхнем уровне
+        path: hello.md
+        alias: 'new-url-path'
+        hidden: false
+    tag:
+        name: Название оглавления внутри тега tag
+        path: custom.md
+        alias: 'new-tag'
+        hidden: true
+```
+
+Параметр `tag` принимает описания тегов:
+
+* `name` - меняет отображаемое на сайте имя оглавления.
+
+* `path` - записывает в оглавление любой контент. Путь до файла с новым содержимым указыватеся относительно файла с конфигурацией OpenAPI.
+
+* `alias` - меняет путь до файла. Все теги на русском языке преобразуются в транслит. С помощью это поля можно указывать произвольное имя файла. Например, есть тег "Регистрация пользователя". Если его не изменить, ссылка на раздел будет выглядеть так `doc.com/registracia_polzovatelya`. Если указать `alias: registration`, ссылка будет иметь вид `doc.com/registration`.
+
+* `hidden` - скрывает раздел оглавления из навигации.
+
+Оглавление верхнего уровня можно настроить с момощью тега `__root__`.
+
+### `leadingPage`
+
+Позволяет настроить все оглавления за раз.
+
+#### Синтаксис
+
+```yaml
+ leadingPage:
+    name: Новое имя всех оглавлений
+    spec:
+        renderMode: hidden
+```
+Теги:
+
+* `name` - меняет название всех оглавлений.
+* `spec.renderMode` - определяет, нужно ли добавлять OpenAPI-спецификацию в оглавление. Если да, необходимо указать значение `renderMode: inline`, в ином случае - `renderMode: hidden`.
+
+### `sandbox`
+
+Позволяет отобржать таб с песочницей, через которую можно отправлять запросы.
+
+#### Синтаксис
+
+```yaml
+sandbox:
+    tabName: Название таба с песочницей
+    host: 'https://sandbox.doc.ru'
+```
+
+## Скрытие полей
+
+```yaml
+x-hidden: true
+```
+Чтобы скрыть параметры операции или поля объекта, добавьте в их описание `x-hidden: true`.
+
+#### Пример использования
+
+```yaml
+- name: example
+    required: false
+    schema:
+      type: string
+      description: "Пример"
+    x-hidden: "true"
+```
+
+## Скрытие описаний
+
+Существует 3 вида фильтрации:
+
+* `filter`;
+* `nobuild`;
+* `noindex`.
+
+Они имеют общий интерфейс фильтрации:
+
+```yaml
+filter:
+    endpoint: tags contains "nobuild" != true
+    tag: name == "noindex"
+```
+
+Поле `endpoint` позволяет пометить конечную точку определенным свойством (зависит от выбранного режима фильтрации) аналогично тому, как поле `tag` помечает теги.
+
+### `filter`
+
+Позволяет указать условие, определяющее нужно ли добавлять конечную точку в сборку.
+
+#### Синтаксис
+
+```yaml
+ filter:
+    endpoint: tags contains "nobuild" != true
+```
+
+#### Пример использования
+
+Необходимо, чтобы незавершенные описания не попали в документацию. Чтобы получить такой результат:
+
+1. Добавьте каждому описанию тег `nobuild` (можно использовать любой тег, но для простоты принято добавлять именно этот).
+
+2. Добавьте фильтр на этот тег:
+
+    ```yaml
+     filter:
+        endpoint: tags contains "nobuild" != true
+    ```
+В результате работы фильтра в документации не будет ненужных страниц.
+
+### `noindex`
+
+Позволяет написать условие, определяющее, будет ли описание индексироваться поисковыми роботами.
+
+#### Синтаксис
+
+```yaml
+noindex:
+    tag: name == "noindex"
+```
+
+#### Пример использования
+
+Необходимо скрыть описание от поисковых роботов. Чтобы получить такой результат:
+
+1. Добавьте каждому описанию тег `noindex` (можно использовать любой тег, но для простоты принято добавлять именно этот).
+2. Добавьте фильтр на этот тег:
+
+    ```yaml
+    noindex:
+        tag: name == "noindex"
+    ```

ru/guides/source-docs.md

@@ -0,0 +1,39 @@
+# Source Docs
+
+Вы можете включить документацию в формате [Source Docs](https://github.com/SourceDocs/SourceDocs) в основной документ.
+
+{% note warning %}
+
+sourcedocs-инклюдер находится в процессе деприкации в пользу [generic-инклюдера](generic.md).
+
+{% endnote %}
+
+#### Пример использования
+
+Проект документации лежит в папке `doc_root`.
+
+Положим результат исполнения Source Docs в папку `doc_root/docs`.
+
+Включим его в документацию внутри `doc_root/toc.yaml`, указав `includer` sourcedocs.
+
+Поставим ссылку на сгенерированную разводящую в основной в `doc_root/index.yaml`.
+
+```yaml
+# doc_root/toc.yaml
+title: documentation
+href: index.yaml
+items:
+  - name: docs
+    include:
+      path: docs
+      includer: sourcedocs
+      mode: link
+```
+
+```yaml
+# doc_root/index.yaml
+title: documentation
+links:
+  - title: docs
+    href: docs/
+```

ru/guides/unarchive.md

@@ -0,0 +1,42 @@
+# Unarchive
+
+Вы можете использовать unarchive-инклюдер чтобы распаковать tarball перед тем как применять другие инклюдеры к контенту внутри него, например generic-инклюдер.
+
+#### Пример использования
+
+Есть `docs.tar` в корне проекта по пути `doc_root/docs.tar`.
+
+Внутри `docs.tar` находится контент, который необходимо включить используя generic-инклюдер.
+
+В этом случае нужно применить цепь инклюдеров `unarchive` -> `generic` для достижения цели.
+
+```yaml
+# doc_root/toc.yaml
+title: documentation
+href: index.yaml
+items:
+...
+   - name: multiple
+     include:
+       path: multiple
+       mode: link
+       includers:
+         # run unarchive includer
+         - name: unarchive
+           # specify tarball you want to unpack as input parameter
+           input: docs.tar
+           # specify output path where tarball content is going to be unpacked
+           output: unpacked
+         # run generic includer
+         - name: generic
+           # specify path from unarchive includers output field as input path
+           input: unpacked
+```
+
+```yaml
+# doc_root/index.yaml
+title: documentation
+links:
+  - title: openapi
+    href: openapi/
+```