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

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

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

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

1. Откройте Быстрый старт.

2. В шаге №1 авторизуйтесь в GitHub.

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

4. В шаге №3 нажмите Создать и создайте проект в Diplodoc.

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

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

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

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

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

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

2. Авторизуйтесь или создайте аккаунт в Yandex Cloud.

   Важно

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

3. Перейдите в консоль Yandex Cloud.

4. Откройте Все сервисы → API Gateway.

   Примечание

   API Gateway — упрощенный сервер в Yandex Cloud, который позволяет обслуживать внешние запросы. Настраивается с помощью OpenAPI спецификации.

5. Нажмите кнопку Создать API-шлюз.

6. Заполните поля Имя* и описание. Поле со звездочкой обязательно для заполнения.

7. В поле Сеть выберите default или свой вариант.

8. Заполните поле Спецификация: можно воспользоваться своей 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-конфигурации измените:

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

9. Нажмите Создать.

10. Если платежный аккаунт не привязан, нажмите Привязать.

11. В результате должен появиться API-шлюз со статусом active.

12. Теперь Yandex Cloud может проксировать документацию на свой url.

13. Чтобы заработало проксирование на внешний домен, создайте новый или загрузите личный сертификат.

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

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

1. Перейдите в консоль.

2. Откройте Все сервисы → Certificate Manager.

3. Нажмите Создать сертификат.

4. На странице выберите Добавить сертификат → Сертификат от Let's Encrypt.

   Примечание

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

5. Заполните поля Имя* и описание. Поле со звездочкой обязательно для заполнения.

6. Укажите Домены*, для которых необходимо добавить сертификат. Поле обязательно для заполнения.

7. Выберите в поле Тип проверки — DNS.

8. Созданный сертификат будет ожидать подтверждения со статусом Validating.

9. Подтвердите, что вы являетесь владельцем домена.

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

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

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

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

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

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

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