Настройка личного домена и его проксирование.

Создание репозитория в Diplodoc

Быстрый старт («Quick Start») — сервис, который поможет создать репозиторий и привязать его к внешнему сервису Diplodoc.

Для создания базовой документации:

Откройте Быстрый старт.
В шаге №1 авторизуйтесь в Github.
В шаге №2 нажмите Создать и создайте репозиторий в Github. В результате будет создан проект с именем «diplodoc-example», предзаполненный командой Diplodoc.
В шаге №3 нажмите Создать и создайте проект в Diplodoc.

После выполнения пошаговой инструкции вы получите сообщение:

Ключи от каталога с документацией в S3.
Идентификатор ключа:
***********************
Секретный ключ:
***********************

Сохраните идентификатор и ключ. После закрытия диалога значение ключа будет недоступно. Ключ будет добавлен в созданный репозиторий автоматически.

Дождитесь завершения релиза, проект будет доступен по ссылке в шаге №3 на странице Быстрого старта.

Подготовка Yandex Cloud для привязки домена

Создание API-шлюза

Зарегистрируйте домен (можно воспользоваться доменным регистратором).
Авторизуйтесь или создайте аккаунт в Yandex Cloud.

Важно

На странице Биллинг убедитесь, что у вас подключен платежный аккаунт и находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его.
Перейдите в консоль Yandex Cloud.
Откройте Все сервисы → API Gateway.

Примечание

API Gateway — упрощенный сервер в Yandex Cloud, который позволяет обслуживать внешние запросы. Настраивается с помощью OpenAPI спецификации.
Нажмите кнопку Создать API-шлюз.
Заполните поля Имя* и описание. Поле со звездочкой обязательно для заполнения.
В поле Сеть выберите default или свой вариант.

Заполните поле Спецификация: можно воспользоваться своей OpenAPI спецификацией или примером.

Пример OpenAPI спецификации

Важно

Вы можете использовать пример OpenAPI спецификации, но не забудьте изменить некоторые важные параметры, такие как: адрес внешнего домена или путь, на который должна проксироваться документация.

OpenAPI Спецификация

openapi: 3.0.0
info:
  title: Proxy Example
  version: 1.0.0
servers:
- url: https://d5dj3947rd2qu5g1lbak.apigw.yandexcloud.net
- url: example-for-your-domain.net
paths:
  /путь/{path+}:
    get:
      x-yc-apigateway-integration:
        headers:
          x-real-host: example-for-your-domain.net
          x-docs-proxy-base: docs
          x-docs-project-name: diplodoc-platform--docs
        http_method: get
        query:
          '*': '*'
        type: http
        url: https://diplodoc-platform--docs.viewer.diplodoc.com/{path}
      parameters:
        - name: path
          in: path
          required: false
          schema:
            type: string

Описание параметров OpenAPI спецификации

Параметр	Описание параметра
`servers`	Настройка вложенных параметров `url` раздела `servers` позволит указать, по какому адресу необходимо проксировать документацию. Для проксирования документации на ваш домен настройте вложенные параметры: Первый параметр `url` содержит адрес, на котором работает API Gateway, — оставьте значение по умолчанию. Для второго параметра `url` укажите внешний домен, на который нужно проксировать документацию.
`paths`	Содержит вложенное правило, которое позволяет конфигурировать ответ для параметра `url` из раздела `servers`. Параметр `/путь/{path+}:`, вложенный в раздел `paths`, указывает, по какому пути должна располагаться документация. Примечание Если вы используете пример OpenAPI спецификации, то документация будет расположена по пути `example-for-your-domain.net/docs`.
`get`	Вложенное правило, которое обрабатывает все get-запросы.
`headers`	Раздел содержит служебные заголовки. Для настройки служебных заголовков: 1. В параметре `x-real-host:` укажите адрес домена. 2. В параметре `x-docs-proxy-base:` укажите каталог, на котором будет размещаться документация. 3. В параметре `x-docs-project-name:`укажите название проекта.
`url`	Параметр, вложенный в правило `get`, содержит адрес, на который перенаправляется документация. Примечание Если вы используете пример OpenAPI спецификации, то документация будет перенаправляться на домен диплодока.
`parameters`	Раздел обрабатывает параметр `path` по заданному правилу.

Важно

Для размещения в корне домена в OpenAPI-конфигурации измените:

У параметра x-docs-proxy-base значение на ' '.
У параметра paths: значение на /{path+}:.

Нажмите Создать.
Если платежный аккаунт не привязан, нажмите Привязать.
В результате должен появиться API-шлюз со статусом active.
Теперь Yandex Cloud может проксировать документацию на свой url.
Чтобы заработало проксирование на внешний домен, создайте новый или загрузите личный сертификат.

Создание/загрузка сертификата

Для создания или загрузки личного сертификата:

Перейдите в консоль.
Откройте Все сервисы → Certificate Manager.
Нажмите Создать сертификат.
На странице выберите Добавить сертификат → Сертификат от Let's Encrypt.

Примечание

Если у вас уже есть сертификат, который зарегистрирован во внешнем сервисе, вы можете использовать его, для этого в выпадающем меню выберите Пользовательский сертификат.
Заполните поля Имя* и описание. Поле со звездочкой обязательно для заполнения.
Укажите Домены*, для которых необходимо добавить сертификат. Поле обязательно для заполнения.
Выберите в поле Тип проверки — DNS.
Созданный сертификат будет ожидать подтверждения со статусом Validating.
Подтвердите, что вы являетесь владельцем домена.

Подтверждение сертификата

Для подтверждения прав на владение доменом:

Перейдите в консоль.
Откройте Все сервисы → Certificate Manager.
Выберите созданный или добавленный сертификат.
Подтвердите права на владение доменом, используя один из предложенных способов.
Права на владение домена подтверждены.
Подключите домен.

Привязка домена к Yandex Cloud

Подключение домена

Для завершения привязки домена к Yandex Cloud:

Откройте Все сервисы → API Gateway.
Выберите созданный API-шлюз.
В левом меню нажмите домены → Подключить.
Выберите созданный сертификат.
Укажите домен.
Нажмите Подключить.
Настройка проксирования на личный домен завершена.

Была ли статья полезна?

Контентная аналитика

Автогенерация и интеграция документации