Генерация из OpenAPI-спецификации

Вы можете сгенерировать документ из OpenAPI-спецификации и включить её в основной документ.

Требования к OpenAPI-спецификации

• Версия используемой спецификации не ниже 3.Х.
• Допускается использование только операторов oneOf и allOf.
• Ограничения на использование базового функционала не накладываются.

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

1. Документационный проект лежит в директории doc_root.

2. OpenAPI-спецификацию размещаем по пути doc_root/openapi.yaml.

3. Включаем её в оглавление doc_root/toc.yaml с помощью openapi-инклюдера.

4. Подключаем разводящую в doc_root/index.yaml.

# doc_root/toc.yaml
title: documentation
href: index.yaml
items:
  - name: openapi
    include:
      path: openapi
      includers:
        - name: openapi
          input: openapi.yaml
      mode: link

# doc_root/index.yaml
title: documentation
links:
  - title: openapi
    href: openapi/

tags

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

Синтаксис

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

Позволяет настроить все оглавления за раз.

Синтаксис

 leadingPage:
    name: Новое имя всех оглавлений
    spec:
        renderMode: hidden

Теги:

• name - меняет название всех оглавлений.
• spec.renderMode - определяет, нужно ли добавлять OpenAPI-спецификацию в оглавление. Если да, необходимо указать значение renderMode: inline, в ином случае - renderMode: hidden.

sandbox

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

Синтаксис

sandbox:
    tabName: Название таба с песочницей
    host: 'https://sandbox.doc.ru'

Скрытие полей

x-hidden: true

Чтобы скрыть параметры операции или поля объекта, добавьте в их описание x-hidden: true.

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

- name: example
    required: false
    schema:
      type: string
      description: "Пример"
    x-hidden: "true"

Скрытие описаний

Существует 3 вида фильтрации:

• filter;
• nobuild;
• noindex.

Они имеют общий интерфейс фильтрации:

filter:
    endpoint: tags contains "nobuild" != true
    tag: name == "noindex"

Поле endpoint позволяет пометить конечную точку определенным свойством (зависит от выбранного режима фильтрации) аналогично тому, как поле tag помечает теги.

filter

Позволяет указать условие, определяющее нужно ли добавлять конечную точку в сборку.

Синтаксис

 filter:
    endpoint: tags contains "nobuild" != true

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

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

1. Добавьте каждому описанию тег nobuild (можно использовать любой тег, но для простоты принято добавлять именно этот).

2. Добавьте фильтр на этот тег:

    filter:
       endpoint: tags contains "nobuild" != true
   

В результате работы фильтра в документации не будет ненужных страниц.

noindex

Позволяет написать условие, определяющее, будет ли описание индексироваться поисковыми роботами.

Синтаксис

noindex:
    tag: name == "noindex"

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

Необходимо скрыть описание от поисковых роботов. Чтобы получить такой результат:

1. Добавьте каждому описанию тег noindex (можно использовать любой тег, но для простоты принято добавлять именно этот).

2. Добавьте фильтр на этот тег:

   noindex:
       tag: name == "noindex"