Собственные домены

По умолчанию документы публикуются на общих адресах Powerduck. Собственный домен позволяет разместить документацию и MCP под вашим именем хоста, чтобы API был представлен под вашим брендом, а не общей ссылкой.

Это платная возможность тарифов Pro и Team, проверяемая через право oas.custom_domain.

Привязка всего хоста или пути

Привязать можно:

• весь хост — api.example.com обслуживает один документ в корне;
• хост с путём — example.com/v1 обслуживает документ по пути /v1.

Привязки к путям позволяют размещать несколько документов на одном хосте:

example.com/v1  -> document A
example.com/v2  -> document B

Это снимает ограничение «один хост на документ» и позволяет использовать базовые пути с версиями.

Адреса на собственном домене

Те же интерфейсы, что доступны по общему адресу, публикуются на привязанном домене с короткими постоянными путями:

Интерфейс	Весь хост	Путь
Текущая спецификация	/oas	/v1/oas
Спецификация закреплённой версии	/v/:version/oas	/v1/v/:version/oas
MCP	/mcp	/v1/mcp

Имя хоста и путь запроса определяют привязанный документ. Предварительные запросы CORS обрабатываются для каждого из этих путей.

Добавление и проверка домена

Домен считается доверенным только после подтверждения владения:

1. Добавьте к документу имя хоста или имя хоста с путём;
2. сервис вернёт привязку и инструкцию по DNS;
3. создайте DNS-запись и запустите проверку;
4. привязка перейдёт из ожидающего состояния в подтверждённое и начнёт обслуживать запросы.

Для подтверждения используется TXT-запись:

Поле	Значение
Тип записи	TXT
Хост	_powerduck-challenge.<your-domain>
Значение	powerduck-verify=<verification-token>

Проверка считывает TXT-запись через DNS и сравнивает токен за постоянное время. Уже подтверждённая привязка сохраняет статус без повторной проверки.

Пример

Для api.example.com добавьте TXT-запись:

_powerduck-challenge.api.example.com
TXT "powerduck-verify=<the-token-shown-for-the-binding>"

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

Управление привязками

• Просматривайте домены документа, их статусы и базовые пути;
• проверяйте ожидающую привязку после добавления DNS-записи;
• удаляйте привязку, чтобы прекратить публикацию документа на этом домене.

Изменения параметров доступа сбрасывают кеш разрешения хоста, поэтому устаревшие привязки не продолжают использоваться.

Управление доступом сохраняется

Собственный домен — это дополнительный адрес, а не обход ограничений:

• документ должен иметь статус ACTIVE;
• документация и MCP включаются отдельно;
• пароль по-прежнему защищает документацию, а ключ доступа — MCP.

См. Управление доступом.

Связанные разделы: Документы и версии, Оплата.