Правки

ru/personal-domain-ya-cloud.md

@@ -2,16 +2,16 @@
 
 ## Создание репозитория в Diplodoc
 
-Быстрый старт («Quick Start») - сервис, который поможет создать репозиторий и привязать его к внешнему сервису Diplodoc.
+Быстрый старт («Quick Start») — сервис, который поможет создать репозиторий и привязать его к внешнему сервису Diplodoc.
 
 Для создания базовой документации:
 
 1. Откройте [Быстрый старт](https://diplodoc.com/quickstart/).
-1. Авторизуйтесь в Github, кликнув по зеленому прямоугольнику с логотипом Github.
+1. В шаге №1 авторизуйтесь в Github.
 
     {% note alert %}
 
-    Если сервис выдаст ошибку «Could not get github state back» - обновите текущую страницу.
+    Если сервис выдаст ошибку «Could not get github state back» — обновите текущую страницу.
     Чтобы обновить страницу нажмите сочетание клавиш **CTRL + F5**.
 
     {% endnote %}
@@ -34,7 +34,7 @@
 
 ## Привязка домена к Yandex Cloud
 
-Для привязки домена к Yandex Cloud:
+### Создание API-шлюза
 
 1. Зарегистрируйте домен (для этого используйте [доменный регистратор](https://yandex.ru/search/?text=доменнный+регистратор)).
 1. Авторизуйтесь или создайте аккаунт в [Yandex Cloud](https://yandex.cloud/).
@@ -45,12 +45,12 @@
 
     {% endnote %}
 
-1. Перейдите в [консоль](https://console.yandex.cloud/folders/).
+1. Перейдите в [консоль Yandex Cloud](https://console.yandex.cloud/folders/).
 1. Откройте **Все сервисы** → **API Gateway**.
     
     {% note info %}
 
-    API Gateway - упрощенный сервер в Yandex Cloud, который позволяет обслуживать внешние запросы. Настраивается с помощью OpenAPI спецификации.
+    API Gateway — упрощенный сервер в Yandex Cloud, который позволяет обслуживать внешние запросы. Настраивается с помощью OpenAPI спецификации.
 
     {% endnote %}
 
@@ -60,9 +60,11 @@
 
 1. В поле **Сеть** выберите `default` или свой вариант.
 
-1. Заполните поле **Спецификация**, используя шаблон спецификации OpenAPI.
+1. Заполните поле **Спецификация**: используйте свою OpenAPI спецификацию или пример ниже, заменив необходимые параметры.
+
+    {% cut "Пример спецификации OpenAPI" %}
 
-    {% cut "Шаблон спецификации OpenAPI" %}
+    #### Спецификация OpenAPI
 
     ```
     openapi: 3.0.0
@@ -71,14 +73,14 @@
       version: 1.0.0
     servers:
     - url: https://d5dj3947rd2qu5g1lbak.apigw.yandexcloud.net
-    - url: домен-на-который-необходимо-спроксировать-документацию
+    - url: example-for-your-domain.net
     paths:
       /путь/{path+}:
         get:
           x-yc-apigateway-integration:
             headers:
-              x-real-host: здесь-должен-быть-домен
-              x-docs-proxy-base: в-каком-каталоге-размещаться
+              x-real-host: example-for-your-domain.net
+              x-docs-proxy-base: docs
               x-docs-project-name: diplodoc-platform--docs
             http_method: get
             query:
@@ -93,19 +95,43 @@
                 type: string
     ```
 
+    #### Описание параметров спецификации OpenAPI
+
     #|
     || Параметр | Описание параметра ||
-    || `servers` | Содержит следующие вложенные параметры:
-    - первый `url` параметр — оставьте по умолчанию,
-    - второй `url`параметр — укажите свой домен. ||
-    || `paths` | Содержит правило и позволяет настраивать путь с помощью вложенного параметра `/путь/{path+}:`, который указывает на каком урле должна располагаться документация. ||
-    || `get` | Вложенное в `paths:` правило, которое объясняет как путь должен обрабатываться. В шаблоне правило обрабатывает все get-запросы. ||
-    || `headers` | Параметр содержит служебные заголовки. ||
+    || `servers` | Раздел содержит следующие вложенные параметры:
+    - Первый `url` параметр содержит адрес, на котором работает API Gateway, — оставьте значение по умолчанию.
+    - Для второго `url` параметра укажите свой домен. ||
+    || `paths` | Содержит вложенное правило, которое позволяет с помощью параметров конфигурировать ответ на корень урла. Вложенный в раздел `paths`, параметр `/путь/{path+}:` указывает по какому адресу должна располагаться документация. 
+
+    {% note info %}
+
+    Если вы используете пример OpenAPI спецификации, то документация будет разсположена по адресу `example-for-your-domain.net/docs`.
+    
+    {% endnote %}||
+    || `get` | Вложенное правило, которое обрабатывает все get-запросы. ||
+    || `headers` | Параметр содержит служебные заголовки:
+    - x-real-host — домен
+    - x-docs-proxy-base: docs — в каком каталоге размещаться
+    - x-docs-project-name: diplodoc-platform--docs —
+    ||
+    || `url` | Параметр, вложенный в правило `get`, содержит адрес, на который перенаправляется документация.
+
+    {% note info %}
+
+    Если вы используете пример OpenAPI спецификации, то документация будет направляться на домен диплодока.
+    
+    {% endnote %}||
+
+    || `parameters` | Раздел обрабатывает параметр `path` по заданному правилу. ||  
     |#
 
     {% note warning %}
 
-    Если нужно размещаться в корне домена, замените ключ параметра `x-docs-proxy-base` на `' '`, а также у параметра `paths` уберите `/путь`, чтобы осталось `/{path+}:`.
+    Для размещения в корне домена:
+    
+    1. Используйте пример OpenAPI-конфигурации.
+    1. Замените ключ параметра `x-docs-proxy-base` на `' '` и у параметра `paths` уберите `/путь`, чтобы осталось `/{path+}:`.
 
     {% endnote %}
 
@@ -114,7 +140,8 @@
 1. Нажмите **Создать**.
 1. Если платежный аккаунт не привязан, нажмите **Привязать**.
 1. В результате должен появиться API-шлюз со статусом `active`.
-1. [Создайте новый или загрузите личный сертификат]((#cert-creating)).
+1. Теперь Yandex Cloud может проксировать документацию на свой url.
+1. Чтобы заработало проксирование на внешний домен, [создайте новый или загрузите личный сертификат]((#cert-creating)).
 
 ### Создание/загрузка сертификата {#cert-creating}