DOCSUP-86795

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-инклюдера](https://diplodoc.com/docs/ru/project/toc#includers).
+
+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://sandox.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/toc.yaml

@@ -152,6 +152,8 @@ items:
     items:
       - name: Контентная аналитика
         href: guides/content-analytics.md
+      - name: Генерация из OpenAPI-спецификации
+        href: guides/openapi.md        
   - name: Вакансии
     hidden: true
     items: