DocfyUiModule.setup(mountPath, app, options?)
Отдаёт docfy-ui (сопутствующий интерфейс документации с прицелом на ИИ из этого пакета) по адресу mountPath. Ту же роль для обычного Swagger UI играют SwaggerModule.setup() и swagger-ui-express.
Использование
Работает и в приложениях на Express (@nestjs/platform-express), и на Fastify (@nestjs/platform-fastify). Для Fastify отдача статики требует необязательной peer-зависимости @fastify/static (npm install @fastify/static). На этот же пакет опирается и сам @nestjs/swagger в своей поддержке Swagger UI под Fastify.
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { DocfyUiModule } from 'nestjs-docfy';
const app = await NestFactory.create(AppModule);
DocfyUiModule.setup('/docs', app); // before SwaggerModule.setup; see staticSpecPath below
const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
SwaggerModule.setup('api', app, document); // exposes /api-json, which docfy-ui fetches by default
await app.listen(3000);Откройте /docs. Больше настраивать нечего: docfy-ui по умолчанию запрашивает /api-json с того же origin.
Параметры
| Option | Type | Default | Description |
|---|---|---|---|
staticSpecPath | string | нет | Path to a pre-built OpenAPI JSON file, served at /api-json instead of the app's live one. |
specs | { name: string; url: string }[] | нет | Extra OpenAPI specs to offer in docfy-ui's spec switcher, so one deployed instance can browse more than one service's documentation. |
openApiDocument | { servers?: { url: string }[] } | нет | Enables the "Try it out" same-origin proxy — pass the same object you already have from SwaggerModule.createDocument(). See below. |
additionalProxyOrigins | string[] | нет | Extra origins the proxy is allowed to forward requests to, beyond what openApiDocument.servers declares. |
guides | { slug, title, content }[] | нет | Narrative markdown pages at /guides/:slug, listed in the sidebar. A guide can embed a live, runnable request via a docfy-try fenced block (single line METHOD /path matching an endpoint in the current spec) — renders the endpoint's real request panel inline instead of just linking to its page. |
proxyAuthorize | (req) => boolean | Promise<boolean> | нет | Decides who may use the proxy (false → 403). Nest guards don't run for the proxy route. Required for the proxy in production. |
allowProxyInProduction | boolean | false | Enables the proxy in production without proxyAuthorize. Only when the mount path is already protected by something else. |
securityHeaders | boolean | true | CSP, nosniff, Referrer-Policy and frame headers on the docs UI. false turns them all off (e.g. helmet already sets them). |
contentSecurityPolicy | string | нет | Replaces the default Content-Security-Policy value. |
cspConnectSrc | string[] | нет | Extra connect-src origins for the default CSP (e.g. API servers "Try it out" calls directly when the spec has no servers[]). |
staticSpecPath (нужен под webpack: true, если вы не используете плагин CLI)
Конвейер метаданных DocfyModule в рантайме не может применить там docs-файлы, поэтому в живом /api-json не будет ничего из того, что эти файлы добавляют. Рекомендуемое автоматическое решение описано в разделе Плагин CLI. Здесь же разбирается ручная альтернатива: подготовить пропатченный документ заранее.
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.jsonИ отдать его:
DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });Вызывайте это до SwaggerModule.setup(). Express разбирает маршруты в порядке регистрации, поэтому на любой запрос к /api-json пропатченный статический документ окажется важнее живого. На Fastify всё иначе: если SwaggerModule.setup() зарегистрирует рядом собственный маршрут /api-json, приложение упадёт на старте с FST_ERR_DUPLICATED_ROUTE. Порядок регистрации там не спасает, так что вместе с staticSpecPath на Fastify направьте SwaggerModule.setup() на другой jsonDocumentUrl либо передайте { raw: false }.
Прокси на том же origin
Включает прокси на том же origin для режима «Try it out» в docfy-ui. Без него браузер отправляет запрос прямо в целевой API и подчиняется его политике CORS. С ним модуль регистрирует маршрут на своём origin (), браузер обращается уже туда, а настоящий запрос прокси делает сам, сервер к серверу, поэтому CORS вообще не при делах. Передайте тот же документ, который у вас уже есть из SwaggerModule.createDocument():
const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
SwaggerModule.setup('api', app, document);
DocfyUiModule.setup('/docs', app, { openApiDocument: document });Белый список прокси строится только из абсолютных URL в массиве servers[] документа плюс всего, что перечислено в additionalProxyOrigins. Неявного запасного варианта «тот же origin, что и у запроса» здесь нет намеренно: его пришлось бы выводить из заголовка Host, которым управляет клиент, а это классический вектор SSRF. Запрос к любому другому origin отклоняется с и заголовком ответа .
Любой другой сбой на уровне прокси (цель недоступна, таймаут, кривой запрос) тоже проставляет , чтобы docfy-ui отличал падение прокси от настоящего ответа 4xx/5xx вашего API. Такие ответы проходят насквозь нетронутыми, со своим статусом, заголовками и телом.
При NODE_ENV=production прокси отключён, пока вы не зададите proxyAuthorize — хук, который решает, кому можно им пользоваться: guards Nest для этого маршрута никогда не выполняются. См. Безопасность и миграция.
DocfyUiModule.setup('/docs', app, {
openApiDocument: document,
proxyAuthorize: async (req) => (await currentUser(req))?.roles.includes('developer') ?? false,
});