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

Создание репозитория в 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. Настройка проксирования на личный домен завершена.